chaos/hack
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
hack/tools/scripts/llm-key-hunter/results/_cache/content/calicksfoxs-droid_smart-api-gateway-omni.json
T
OpenCode 68a9071cf1 feat: reconcile local master with origin (exa/hot-platform hunters, leaks ledger, latest results) 
Local branch had diverged from origin/master (sibling commits on the same base). Rewrote local history linearly on top of origin/master, folding in all local content: exa/hot-platform discovery hunters, leaks ledger, nightly sweep orchestrator, updated .gitignore and skill docs, plus the latest hunt output and vault state. Remote-only files (vault keys, channel scripts) were restored rather than dropped, so the resulting tree is a full union of both sides.
2026-08-07 12:53:47 +08:00

1 line
4.0 MiB
Plaintext
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{"repo": "calicksfoxs-droid/smart-api-gateway-omni", "files": {"tests/snapshots/provider/translate-path.json": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785674319.67871, "n": 133845, "h": "1589b9224009e066", "c": "{\n \"adapta-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://agent.adapta.one/api/chat/stream/v1\",\n \"stream\": \"https://agent.adapta.one/api/chat/stream/v1\"\n }\n },\n \"agentrouter\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, sdk-cli)\",\n \"X-Stainless-Arch\": \"<ARCH>\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-OS\": \"MacOS\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"accept-encoding\": \"gzip, deflate, br, zstd\",\n \"anthropic-beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24\",\n \"anthropic-dangerous-direct-browser-access\": \"true\",\n \"anthropic-version\": \"2023-06-01\",\n \"x-api-key\": \"<CRED>\",\n \"x-app\": \"cli\"\n },\n \"nonStream\": {\n \"Accept\": \"application/json\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, sdk-cli)\",\n \"X-Stainless-Arch\": \"<ARCH>\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-OS\": \"MacOS\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"accept-encoding\": \"gzip, deflate, br, zstd\",\n \"anthropic-beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24\",\n \"anthropic-dangerous-direct-browser-access\": \"true\",\n \"anthropic-version\": \"2023-06-01\",\n \"x-api-key\": \"<CRED>\",\n \"x-app\": \"cli\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, sdk-cli)\",\n \"X-Stainless-Arch\": \"<ARCH>\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-OS\": \"MacOS\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"accept-encoding\": \"gzip, deflate, br, zstd\",\n \"anthropic-beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24\",\n \"anthropic-dangerous-direct-browser-access\": \"true\",\n \"anthropic-version\": \"2023-06-01\",\n \"x-api-key\": \"<CRED>\",\n \"x-app\": \"cli\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://agentrouter.org/v1/messages?beta=true\",\n \"stream\": \"https://agentrouter.org/v1/messages?beta=true\"\n }\n },\n \"agy\": {\n \"format\": \"antigravity\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 (<PLATFORM>) Chrome/142.0.7444.175 Electron/39.2.3\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 (<PLATFORM>) Chrome/142.0.7444.175 Electron/39.2.3\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 (<PLATFORM>) Chrome/142.0.7444.175 Electron/39.2.3\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://daily-cloudcode-pa.googleapis.com/v1internal:generateContent\",\n \"stream\": \"https://daily-cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse\"\n }\n },\n \"ai21\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.ai21.com/studio/v1/chat/completions\",\n \"stream\": \"https://api.ai21.com/studio/v1/chat/completions\"\n }\n },\n \"aimlapi\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.aimlapi.com/v1/chat/completions\",\n \"stream\": \"https://api.aimlapi.com/v1/chat/completions\"\n }\n },\n \"alibaba\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions\",\n \"stream\": \"https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions\"\n }\n },\n \"alibaba-cn\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions\",\n \"stream\": \"https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions\"\n }\n },\n \"anthropic\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"nonStream\": {\n \"Anthropic-Beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.anthropic.com/v1/messages?beta=true\",\n \"stream\": \"https://api.anthropic.com/v1/messages?beta=true\"\n }\n },\n \"antigravity\": {\n \"format\": \"antigravity\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 (<PLATFORM>) Chrome/142.0.7444.175 Electron/39.2.3\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 (<PLATFORM>) Chrome/142.0.7444.175 Electron/39.2.3\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 (<PLATFORM>) Chrome/142.0.7444.175 Electron/39.2.3\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://daily-cloudcode-pa.googleapis.com/v1internal:generateContent\",\n \"stream\": \"https://daily-cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse\"\n }\n },\n \"api-airforce\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.airforce/v1/chat/completions\",\n \"stream\": \"https://api.airforce/v1/chat/completions\"\n }\n },\n \"auggie\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"auggie://cli/stdio\",\n \"stream\": \"auggie://cli/stdio\"\n }\n },\n \"bai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.b.ai/v1/chat/completions\",\n \"stream\": \"https://api.b.ai/v1/chat/completions\"\n }\n },\n \"baichuan\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.baichuan-ai.com/v1/chat/completions\",\n \"stream\": \"https://api.baichuan-ai.com/v1/chat/completions\"\n }\n },\n \"baidu\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://qianfan.baidubce.com/v2/chat/completions\",\n \"stream\": \"https://qianfan.baidubce.com/v2/chat/completions\"\n }\n },\n \"bailian-coding-plan\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://coding-intl.dashscope.aliyuncs.com/apps/anthropic/v1\",\n \"stream\": \"https://coding-intl.dashscope.aliyuncs.com/apps/anthropic/v1\"\n }\n },\n \"baseten\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://inference.baseten.co/v1/chat/completions\",\n \"stream\": \"https://inference.baseten.co/v1/chat/completions\"\n }\n },\n \"bazaarlink\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://bazaarlink.ai/api/v1/chat/completions\",\n \"stream\": \"https://bazaarlink.ai/api/v1/chat/completions\"\n }\n },\n \"bedrock\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {}\n },\n \"blackbox\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.blackbox.ai/v1/chat/completions\",\n \"stream\": \"https://api.blackbox.ai/v1/chat/completions\"\n }\n },\n \"blackbox-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://app.blackbox.ai/api/chat\",\n \"stream\": \"https://app.blackbox.ai/api/chat\"\n }\n },\n \"bluesminds\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.bluesminds.com/v1/chat/completions\",\n \"stream\": \"https://api.bluesminds.com/v1/chat/completions\"\n }\n },\n \"byteplus\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ark.ap-southeast.bytepluses.com/api/v3/chat/completions\",\n \"stream\": \"https://ark.ap-southeast.bytepluses.com/api/v3/chat/completions\"\n }\n },\n \"bytez\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.bytez.com/models/v2/openai/v1/chat/completions\",\n \"stream\": \"https://api.bytez.com/models/v2/openai/v1/chat/completions\"\n }\n },\n \"cerebras\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.cerebras.ai/v1/chat/completions\",\n \"stream\": \"https://api.cerebras.ai/v1/chat/completions\"\n }\n },\n \"charm-hyper\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://hyper.charm.land/v1/chat/completions\",\n \"stream\": \"https://hyper.charm.land/v1/chat/completions\"\n }\n },\n \"chatgpt-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chatgpt.com/backend-api/conversation\",\n \"stream\": \"https://chatgpt.com/backend-api/conversation\"\n }\n },\n \"chipotle\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://amelia.chipotle.com\",\n \"stream\": \"https://amelia.chipotle.com\"\n }\n },\n \"chutes\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.chutesai.com/v1/chat/completions\",\n \"stream\": \"https://api.chutesai.com/v1/chat/completions\"\n }\n },\n \"claude\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Beta\": \"claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Dangerous-Direct-Browser-Access\": \"true\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, cli)\",\n \"X-App\": \"cli\",\n \"X-Stainless-Arch\": \"<ARCH>\",\n \"X-Stainless-Helper-Method\": \"stream\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"<OS>\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"x-api-key\": \"<CRED>\"\n },\n \"nonStream\": {\n \"Anthropic-Beta\": \"claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Dangerous-Direct-Browser-Access\": \"true\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, cli)\",\n \"X-App\": \"cli\",\n \"X-Stainless-Arch\": \"<ARCH>\",\n \"X-Stainless-Helper-Method\": \"stream\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"<OS>\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"x-api-key\": \"<CRED>\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Beta\": \"claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Dangerous-Direct-Browser-Access\": \"true\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, cli)\",\n \"X-App\": \"cli\",\n \"X-Stainless-Arch\": \"<ARCH>\",\n \"X-Stainless-Helper-Method\": \"stream\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"<OS>\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"x-api-key\": \"<CRED>\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.anthropic.com/v1/messages?beta=true\",\n \"stream\": \"https://api.anthropic.com/v1/messages?beta=true\"\n }\n },\n \"claude-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://claude.ai/api/organizations\",\n \"stream\": \"https://claude.ai/api/organizations\"\n }\n },\n \"cline\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"User-Agent\": \"OmniRoute/<APP>\",\n \"X-CLIENT-TYPE\": \"omniroute\",\n \"X-CLIENT-VERSION\": \"<APP>\",\n \"X-CORE-VERSION\": \"<APP>\",\n \"X-IS-MULTIROOT\": \"false\",\n \"X-PLATFORM\": \"<PLATFORM>\",\n \"X-PLATFORM-VERSION\": \"<NODE>\",\n \"X-Title\": \"Cline\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"User-Agent\": \"OmniRoute/<APP>\",\n \"X-CLIENT-TYPE\": \"omniroute\",\n \"X-CLIENT-VERSION\": \"<APP>\",\n \"X-CORE-VERSION\": \"<APP>\",\n \"X-IS-MULTIROOT\": \"false\",\n \"X-PLATFORM\": \"<PLATFORM>\",\n \"X-PLATFORM-VERSION\": \"<NODE>\",\n \"X-Title\": \"Cline\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"User-Agent\": \"OmniRoute/<APP>\",\n \"X-CLIENT-TYPE\": \"omniroute\",\n \"X-CLIENT-VERSION\": \"<APP>\",\n \"X-CORE-VERSION\": \"<APP>\",\n \"X-IS-MULTIROOT\": \"false\",\n \"X-PLATFORM\": \"<PLATFORM>\",\n \"X-PLATFORM-VERSION\": \"<NODE>\",\n \"X-Title\": \"Cline\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.cline.bot/api/v1/chat/completions\",\n \"stream\": \"https://api.cline.bot/api/v1/chat/completions\"\n }\n },\n \"clinepass\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"X-Title\": \"Cline\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"X-Title\": \"Cline\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"X-Title\": \"Cline\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.cline.bot/api/v1/chat/completions\",\n \"stream\": \"https://api.cline.bot/api/v1/chat/completions\"\n }\n },\n \"cloudflare-ai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.cloudflare.com/client/v4/accounts\",\n \"stream\": \"https://api.cloudflare.com/client/v4/accounts\"\n }\n },\n \"codebuddy-cn\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"CLI/2.108.1 CodeBuddy/2.108.1\",\n \"X-IDE-Name\": \"CLI\",\n \"X-IDE-Type\": \"CLI\",\n \"X-Product\": \"SaaS\",\n \"x-codebuddy-request\": \"1\",\n \"x-requested-with\": \"XMLHttpRequest\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"CLI/2.108.1 CodeBuddy/2.108.1\",\n \"X-IDE-Name\": \"CLI\",\n \"X-IDE-Type\": \"CLI\",\n \"X-Product\": \"SaaS\",\n \"x-codebuddy-request\": \"1\",\n \"x-requested-with\": \"XMLHttpRequest\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"CLI/2.108.1 CodeBuddy/2.108.1\",\n \"X-IDE-Name\": \"CLI\",\n \"X-IDE-Type\": \"CLI\",\n \"X-Product\": \"SaaS\",\n \"x-codebuddy-request\": \"1\",\n \"x-requested-with\": \"XMLHttpRequest\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://copilot.tencent.com/v2/chat/completions\",\n \"stream\": \"https://copilot.tencent.com/v2/chat/completions\"\n }\n },\n \"codestral\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://codestral.mistral.ai/v1/chat/completions\",\n \"stream\": \"https://codestral.mistral.ai/v1/chat/completions\"\n }\n },\n \"codex\": {\n \"format\": \"openai-responses\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"Openai-Beta\": \"responses=experimental\",\n \"User-Agent\": \"codex-cli/0.144.1 (<OS>; <ARCH>)\",\n \"Version\": \"0.144.1\",\n \"X-Codex-Beta-Features\": \"responses_websockets\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"Openai-Beta\": \"responses=experimental\",\n \"User-Agent\": \"codex-cli/0.144.1 (<OS>; <ARCH>)\",\n \"Version\": \"0.144.1\",\n \"X-Codex-Beta-Features\": \"responses_websockets\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"Openai-Beta\": \"responses=experimental\",\n \"User-Agent\": \"codex-cli/0.144.1 (<OS>; <ARCH>)\",\n \"Version\": \"0.144.1\",\n \"X-Codex-Beta-Features\": \"responses_websockets\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chatgpt.com/backend-api/codex/responses\",\n \"stream\": \"https://chatgpt.com/backend-api/codex/responses\"\n }\n },\n \"cohere\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.cohere.com/compatibility/v1/chat/completions\",\n \"stream\": \"https://api.cohere.com/compatibility/v1/chat/completions\"\n }\n },\n \"command-code\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.commandcode.ai\",\n \"stream\": \"https://api.commandcode.ai\"\n }\n },\n \"copilot-m365-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"wss://substrate.office.com/m365Copilot/Chathub\",\n \"stream\": \"wss://substrate.office.com/m365Copilot/Chathub\"\n }\n },\n \"copilot-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"wss://copilot.microsoft.com/c/api/chat?api-version=2\",\n \"stream\": \"wss://copilot.microsoft.com/c/api/chat?api-version=2\"\n }\n },\n \"coze\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.coze.com/v1/chat/completions\",\n \"stream\": \"https://api.coze.com/v1/chat/completions\"\n }\n },\n \"crof\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://crof.ai/v1/chat/completions\",\n \"stream\": \"https://crof.ai/v1/chat/completions\"\n }\n },\n \"cursor\": {\n \"format\": \"cursor\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/connect+proto\",\n \"User-Agent\": \"Cursor/3.9\",\n \"connect-accept-encoding\": \"gzip\",\n \"connect-protocol-version\": \"1\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/connect+proto\",\n \"User-Agent\": \"Cursor/3.9\",\n \"connect-accept-encoding\": \"gzip\",\n \"connect-protocol-version\": \"1\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/connect+proto\",\n \"User-Agent\": \"Cursor/3.9\",\n \"connect-accept-encoding\": \"gzip\",\n \"connect-protocol-version\": \"1\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api2.cursor.sh\",\n \"stream\": \"https://api2.cursor.sh\"\n }\n },\n \"databricks\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://adb-0000000000000000.0.azuredatabricks.net/serving-endpoints\",\n \"stream\": \"https://adb-0000000000000000.0.azuredatabricks.net/serving-endpoints\"\n }\n },\n \"deepinfra\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.deepinfra.com/v1/openai/chat/completions\",\n \"stream\": \"https://api.deepinfra.com/v1/openai/chat/completions\"\n }\n },\n \"deepseek\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.deepseek.com/v1/chat/completions\",\n \"stream\": \"https://api.deepseek.com/v1/chat/completions\"\n }\n },\n \"deepseek-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chat.deepseek.com/api/v0/chat/completion\",\n \"stream\": \"https://chat.deepseek.com/api/v0/chat/completion\"\n }\n },\n \"devin-cli\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"devin://acp/stdio\",\n \"stream\": \"devin://acp/stdio\"\n }\n },\n \"dgrid\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.dgrid.ai/v1/chat/completions\",\n \"stream\": \"https://api.dgrid.ai/v1/chat/completions\"\n }\n },\n \"dify\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.dify.ai/v1/chat/completions\",\n \"stream\": \"https://api.dify.ai/v1/chat/completions\"\n }\n },\n \"digitalocean\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://inference.do-ai.run/v1/chat/completions\",\n \"stream\": \"https://inference.do-ai.run/v1/chat/completions\"\n }\n },\n \"dit\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.dit.ai/v1/chat/completions\",\n \"stream\": \"https://api.dit.ai/v1/chat/completions\"\n }\n },\n \"doubao\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\",\n \"stream\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\"\n }\n },\n \"doubao-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://www.dola.com/chat/completion\",\n \"stream\": \"https://www.dola.com/chat/completion\"\n }\n },\n \"duckduckgo-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://duckduckgo.com/duckchat/v1/chat\",\n \"stream\": \"https://duckduckgo.com/duckchat/v1/chat\"\n }\n },\n \"factory\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.factory.ai/v1/chat/completions\",\n \"stream\": \"https://api.factory.ai/v1/chat/completions\"\n }\n },\n \"featherless-ai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.featherless.ai/v1/chat/completions\",\n \"stream\": \"https://api.featherless.ai/v1/chat/completions\"\n }\n },\n \"fireworks\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.fireworks.ai/inference/v1/chat/completions\",\n \"stream\": \"https://api.fireworks.ai/inference/v1/chat/completions\"\n }\n },\n \"freeaiapikey\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://freeaiapikey.com/v1/chat/completions\",\n \"stream\": \"https://freeaiapikey.com/v1/chat/completions\"\n }\n },\n \"freemodel-dev\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.freemodel.dev/v1/chat/completions\",\n \"stream\": \"https://api.freemodel.dev/v1/chat/completions\"\n }\n },\n \"friendliai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.friendli.ai/serverless/v1/chat/completions\",\n \"stream\": \"https://api.friendli.ai/serverless/v1/chat/completions\"\n }\n },\n \"galadriel\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.galadriel.ai/v1/chat/completions\",\n \"stream\": \"https://api.galadriel.ai/v1/chat/completions\"\n }\n },\n \"gemini\": {\n \"format\": \"gemini\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Content-Type\": \"application/json\",\n \"x-goog-api-key\": \"<CRED>\"\n },\n \"nonStream\": {\n \"Content-Type\": \"application/json\",\n \"x-goog-api-key\": \"<CRED>\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://generativelanguage.googleapis.com/v1beta/models/test-model:generateContent\",\n \"stream\": \"https://generativelanguage.googleapis.com/v1beta/models/test-model:streamGenerateContent?alt=sse\"\n }\n },\n \"gemini-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://gemini.google.com/app\",\n \"stream\": \"https://gemini.google.com/app\"\n }\n },\n \"gigachat\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://gigachat.devices.sberbank.ru/api/v1\",\n \"stream\": \"https://gigachat.devices.sberbank.ru/api/v1\"\n }\n },\n \"github\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"X-Initiator\": \"user\",\n \"copilot-integration-id\": \"vscode-chat\",\n \"editor-plugin-version\": \"copilot-chat/0.54.0\",\n \"editor-version\": \"vscode/1.126.0\",\n \"openai-intent\": \"conversation-panel\",\n \"user-agent\": \"GitHubCopilotChat/0.54.0\",\n \"x-github-api-version\": \"2026-06-01\",\n \"x-request-id\": \"<UUID>\",\n \"x-vscode-user-agent-library-version\": \"electron-fetch\"\n },\n \"nonStream\": {\n \"Accept\": \"application/json\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"X-Initiator\": \"user\",\n \"copilot-integration-id\": \"vscode-chat\",\n \"editor-plugin-version\": \"copilot-chat/0.54.0\",\n \"editor-version\": \"vscode/1.126.0\",\n \"openai-intent\": \"conversation-panel\",\n \"user-agent\": \"GitHubCopilotChat/0.54.0\",\n \"x-github-api-version\": \"2026-06-01\",\n \"x-request-id\": \"<UUID>\",\n \"x-vscode-user-agent-library-version\": \"electron-fetch\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"X-Initiator\": \"user\",\n \"copilot-integration-id\": \"vscode-chat\",\n \"editor-plugin-version\": \"copilot-chat/0.54.0\",\n \"editor-version\": \"vscode/1.126.0\",\n \"openai-intent\": \"conversation-panel\",\n \"user-agent\": \"GitHubCopilotChat/0.54.0\",\n \"x-github-api-version\": \"2026-06-01\",\n \"x-request-id\": \"<UUID>\",\n \"x-vscode-user-agent-library-version\": \"electron-fetch\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.githubcopilot.com/chat/completions\",\n \"stream\": \"https://api.githubcopilot.com/chat/completions\"\n }\n },\n \"github-models\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"X-GitHub-Api-Version\": \"2022-11-28\"\n },\n \"nonStream\": {\n \"Accept\": \"application/vnd.github+json\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"X-GitHub-Api-Version\": \"2022-11-28\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"X-GitHub-Api-Version\": \"2022-11-28\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://models.github.ai/inference/chat/completions\",\n \"stream\": \"https://models.github.ai/inference/chat/completions\"\n }\n },\n \"gitlab-duo\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://gitlab.com/api/v4/code_suggestions/completions\",\n \"stream\": \"https://gitlab.com/api/v4/code_suggestions/completions\"\n }\n },\n \"gitlawb\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (<OS>; <ARCH>)\",\n \"X-Title\": \"OpenClaude CLI\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (<OS>; <ARCH>)\",\n \"X-Title\": \"OpenClaude CLI\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (<OS>; <ARCH>)\",\n \"X-Title\": \"OpenClaude CLI\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://opengateway.gitlawb.com/v1/xiaomi-mimo\",\n \"stream\": \"https://opengateway.gitlawb.com/v1/xiaomi-mimo\"\n }\n },\n \"gitlawb-gmi\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (<OS>; <ARCH>)\",\n \"X-Title\": \"OpenClaude CLI\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (<OS>; <ARCH>)\",\n \"X-Title\": \"OpenClaude CLI\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (<OS>; <ARCH>)\",\n \"X-Title\": \"OpenClaude CLI\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://opengateway.gitlawb.com/v1/gmi-cloud\",\n \"stream\": \"https://opengateway.gitlawb.com/v1/gmi-cloud\"\n }\n },\n \"glm\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.z.ai/api/coding/paas/v4/chat/completions\",\n \"stream\": \"https://api.z.ai/api/coding/paas/v4/chat/completions\"\n }\n },\n \"glm-cn\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://open.bigmodel.cn/api/coding/paas/v4/chat/completions\",\n \"stream\": \"https://open.bigmodel.cn/api/coding/paas/v4/chat/completions\"\n }\n },\n \"glmt\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.z.ai/api/coding/paas/v4/chat/completions\",\n \"stream\": \"https://api.z.ai/api/coding/paas/v4/chat/completions\"\n }\n },\n \"grok-cli\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://cli-chat-proxy.grok.com/v1/chat/completions\",\n \"stream\": \"https://cli-chat-proxy.grok.com/v1/chat/completions\"\n }\n },\n \"grok-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://grok.com/rest/app-chat/conversations/new\",\n \"stream\": \"https://grok.com/rest/app-chat/conversations/new\"\n }\n },\n \"groq\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.groq.com/openai/v1/chat/completions\",\n \"stream\": \"https://api.groq.com/openai/v1/chat/completions\"\n }\n },\n \"hackclub\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ai.hackclub.com/proxy/v1/chat/completions\",\n \"stream\": \"https://ai.hackclub.com/proxy/v1/chat/completions\"\n }\n },\n \"haiper\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.haiper.ai/v1\",\n \"stream\": \"https://api.haiper.ai/v1\"\n }\n },\n \"hcnsec\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.hcnsec.cn/v1/chat/completions\",\n \"stream\": \"https://api.hcnsec.cn/v1/chat/completions\"\n }\n },\n \"heroku\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://us.inference.heroku.com/v1/chat/completions\",\n \"stream\": \"https://us.inference.heroku.com/v1/chat/completions\"\n }\n },\n \"huggingchat\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://huggingface.co/chat/conversation\",\n \"stream\": \"https://huggingface.co/chat/conversation\"\n }\n },\n \"huggingface\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://router.huggingface.co/v1/chat/completions\",\n \"stream\": \"https://router.huggingface.co/v1/chat/completions\"\n }\n },\n \"hyperbolic\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.hyperbolic.xyz/v1/chat/completions\",\n \"stream\": \"https://api.hyperbolic.xyz/v1/chat/completions\"\n }\n },\n \"ideogram\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.ideogram.ai\",\n \"stream\": \"https://api.ideogram.ai\"\n }\n },\n \"iflytek\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://spark-api.xf-yun.com/v1/chat/completions\",\n \"stream\": \"https://spark-api.xf-yun.com/v1/chat/completions\"\n }\n },\n \"inference-net\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.inference.net/v1/chat/completions\",\n \"stream\": \"https://api.inference.net/v1/chat/completions\"\n }\n },\n \"inner-ai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chatapi.innerai.com/chat\",\n \"stream\": \"https://chatapi.innerai.com/chat\"\n }\n },\n \"kenari\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://kenari.id/v1/chat/completions\",\n \"stream\": \"https://kenari.id/v1/chat/completions\"\n }\n },\n \"kie\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.kie.ai/v1/chat/completions\",\n \"stream\": \"https://api.kie.ai/v1/chat/completions\"\n }\n },\n \"kilo-gateway\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.kilo.ai/api/gateway/chat/completions\",\n \"stream\": \"https://api.kilo.ai/api/gateway/chat/completions\"\n }\n },\n \"kilocode\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"X-KILOCODE-EDITORNAME\": \"OmniRoute\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"X-KILOCODE-EDITORNAME\": \"OmniRoute\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"X-KILOCODE-EDITORNAME\": \"OmniRoute\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.kilo.ai/api/openrouter/chat/completions\",\n \"stream\": \"https://api.kilo.ai/api/openrouter/chat/completions\"\n }\n },\n \"kimi\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.moonshot.ai/v1/chat/completions\",\n \"stream\": \"https://api.moonshot.ai/v1/chat/completions\"\n }\n },\n \"kimi-coding\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.kimi.com/coding/v1/messages?beta=true\",\n \"stream\": \"https://api.kimi.com/coding/v1/messages?beta=true\"\n }\n },\n \"kimi-coding-apikey\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.kimi.com/coding/v1/messages\",\n \"stream\": \"https://api.kimi.com/coding/v1/messages\"\n }\n },\n \"kimi-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://www.kimi.com\",\n \"stream\": \"https://www.kimi.com\"\n }\n },\n \"kiro\": {\n \"format\": \"kiro\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"AWS-SDK-JS/3.0.0 kiro-ide/1.0.0\",\n \"X-Amz-Target\": \"AmazonCodeWhispererStreamingService.GenerateAssistantResponse\",\n \"X-Amz-User-Agent\": \"aws-sdk-js/3.0.0 kiro-ide/1.0.0\"\n },\n \"nonStream\": {\n \"Accept\": \"application/vnd.amazon.eventstream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"AWS-SDK-JS/3.0.0 kiro-ide/1.0.0\",\n \"X-Amz-Target\": \"AmazonCodeWhispererStreamingService.GenerateAssistantResponse\",\n \"X-Amz-User-Agent\": \"aws-sdk-js/3.0.0 kiro-ide/1.0.0\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"AWS-SDK-JS/3.0.0 kiro-ide/1.0.0\",\n \"X-Amz-Target\": \"AmazonCodeWhispererStreamingService.GenerateAssistantResponse\",\n \"X-Amz-User-Agent\": \"aws-sdk-js/3.0.0 kiro-ide/1.0.0\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://codewhisperer.us-east-1.amazonaws.com/generateAssistantResponse\",\n \"stream\": \"https://codewhisperer.us-east-1.amazonaws.com/generateAssistantResponse\"\n }\n },\n \"lambda-ai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.lambda.ai/v1/chat/completions\",\n \"stream\": \"https://api.lambda.ai/v1/chat/completions\"\n }\n },\n \"leonardo\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://cloud.leonardo.ai/api/rest/v1\",\n \"stream\": \"https://cloud.leonardo.ai/api/rest/v1\"\n }\n },\n \"liquid\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.liquid.ai/v1/chat/completions\",\n \"stream\": \"https://api.liquid.ai/v1/chat/completions\"\n }\n },\n \"llamagate\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://llamagate.ai/v1/chat/completions\",\n \"stream\": \"https://llamagate.ai/v1/chat/completions\"\n }\n },\n \"llm7\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.llm7.io/v1/chat/completions\",\n \"stream\": \"https://api.llm7.io/v1/chat/completions\"\n }\n },\n \"lmarena\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://arena.ai/nextjs-api/stream/create-evaluation\",\n \"stream\": \"https://arena.ai/nextjs-api/stream/create-evaluation\"\n }\n },\n \"longcat\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.longcat.chat/openai/v1/chat/completions\",\n \"stream\": \"https://api.longcat.chat/openai/v1/chat/completions\"\n }\n },\n \"maritalk\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Key <CRED>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Key <CRED>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Key <CRED>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chat.maritaca.ai/api\",\n \"stream\": \"https://chat.maritaca.ai/api\"\n }\n },\n \"meta-llama\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.llama.com/compat/v1/chat/completions\",\n \"stream\": \"https://api.llama.com/compat/v1/chat/completions\"\n }\n },\n \"mimocode\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.xiaomimimo.com\",\n \"stream\": \"https://api.xiaomimimo.com\"\n }\n },\n \"minimax\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.minimax.io/anthropic/v1/messages?beta=true\",\n \"stream\": \"https://api.minimax.io/anthropic/v1/messages?beta=true\"\n }\n },\n \"minimax-cn\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.minimaxi.com/anthropic/v1/messages?beta=true\",\n \"stream\": \"https://api.minimaxi.com/anthropic/v1/messages?beta=true\"\n }\n },\n \"mistral\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.mistral.ai/v1/chat/completions\",\n \"stream\": \"https://api.mistral.ai/v1/chat/completions\"\n }\n },\n \"modal\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.modal.ai/v1/chat/completions\",\n \"stream\": \"https://api.modal.ai/v1/chat/completions\"\n }\n },\n \"modelscope\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api-inference.modelscope.cn/v1/chat/completions\",\n \"stream\": \"https://api-inference.modelscope.cn/v1/chat/completions\"\n }\n },\n \"monsterapi\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.monsterapi.ai/v1/chat/completions\",\n \"stream\": \"https://api.monsterapi.ai/v1/chat/completions\"\n }\n },\n \"moonshot\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.moonshot.ai/v1/chat/completions\",\n \"stream\": \"https://api.moonshot.ai/v1/chat/completions\"\n }\n },\n \"morph\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.morphllm.com/v1/chat/completions\",\n \"stream\": \"https://api.morphllm.com/v1/chat/completions\"\n }\n },\n \"muse-spark-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://www.meta.ai/api/graphql\",\n \"stream\": \"https://www.meta.ai/api/graphql\"\n }\n },\n \"nanogpt\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://nano-gpt.com/api/v1/chat/completions\",\n \"stream\": \"https://nano-gpt.com/api/v1/chat/completions\"\n }\n },\n \"nebius\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.tokenfactory.nebius.com/v1/chat/completions\",\n \"stream\": \"https://api.tokenfactory.nebius.com/v1/chat/completions\"\n }\n },\n \"nlpcloud\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.nlpcloud.io/v1/chat/completions\",\n \"stream\": \"https://api.nlpcloud.io/v1/chat/completions\"\n }\n },\n \"nous-research\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://inference-api.nousresearch.com/v1/chat/completions\",\n \"stream\": \"https://inference-api.nousresearch.com/v1/chat/completions\"\n }\n },\n \"novita\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.novita.ai/openai/v1/chat/completions\",\n \"stream\": \"https://api.novita.ai/openai/v1/chat/completions\"\n }\n },\n \"nscale\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://inference.api.nscale.com/v1/chat/completions\",\n \"stream\": \"https://inference.api.nscale.com/v1/chat/completions\"\n }\n },\n \"nube\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ai.nube.sh/api/v1/chat/completions\",\n \"stream\": \"https://ai.nube.sh/api/v1/chat/completions\"\n }\n },\n \"nvidia\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://integrate.api.nvidia.com/v1/chat/completions\",\n \"stream\": \"https://integrate.api.nvidia.com/v1/chat/completions\"\n }\n },\n \"ollama-cloud\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ollama.com/v1/chat/completions\",\n \"stream\": \"https://ollama.com/v1/chat/completions\"\n }\n },\n \"openadapter\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.openadapter.in/v1/chat/completions\",\n \"stream\": \"https://api.openadapter.in/v1/chat/completions\"\n }\n },\n \"openai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.openai.com/v1/chat/completions\",\n \"stream\": \"https://api.openai.com/v1/chat/completions\"\n }\n },\n \"opencode\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://opencode.ai/zen/v1\",\n \"stream\": \"https://opencode.ai/zen/v1\"\n }\n },\n \"opencode-go\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://opencode.ai/zen/go/v1\",\n \"stream\": \"https://opencode.ai/zen/go/v1\"\n }\n },\n \"opencode-zen\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://opencode.ai/zen/v1\",\n \"stream\": \"https://opencode.ai/zen/v1\"\n }\n },\n \"openrouter\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://openrouter.ai/api/v1/chat/completions\",\n \"stream\": \"https://openrouter.ai/api/v1/chat/completions\"\n }\n },\n \"openvecta\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.openvecta.com/v1/chat/completions\",\n \"stream\": \"https://api.openvecta.com/v1/chat/completions\"\n }\n },\n \"orcarouter\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.orcarouter.ai/v1\",\n \"stream\": \"https://api.orcarouter.ai/v1\"\n }\n },\n \"ovhcloud\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://oai.endpoints.kepler.ai.cloud.ovh.net/v1/chat/completions\",\n \"stream\": \"https://oai.endpoints.kepler.ai.cloud.ovh.net/v1/chat/completions\"\n }\n },\n \"perplexity\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.perplexity.ai/chat/completions\",\n \"stream\": \"https://api.perplexity.ai/chat/completions\"\n }\n },\n \"perplexity-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://www.perplexity.ai/rest/sse/perplexity_ask\",\n \"stream\": \"https://www.perplexity.ai/rest/sse/perplexity_ask\"\n }\n },\n \"pioneer\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"nonStream\": {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.pioneer.ai/v1/chat/completions\",\n \"stream\": \"https://api.pioneer.ai/v1/chat/completions\"\n }\n },\n \"pollinations\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://gen.pollinations.ai/v1/chat/completions\",\n \"stream\": \"https://gen.pollinations.ai/v1/chat/completions\"\n }\n },\n \"predibase\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://serving.app.predibase.com/v1/chat/completions\",\n \"stream\": \"https://serving.app.predibase.com/v1/chat/completions\"\n }\n },\n \"publicai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.publicai.co/v1/chat/completions\",\n \"stream\": \"https://api.publicai.co/v1/chat/completions\"\n }\n },\n \"puter\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.puter.com/puterai/openai/v1/chat/completions\",\n \"stream\": \"https://api.puter.com/puterai/openai/v1/chat/completions\"\n }\n },\n \"qianfan\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://qianfan.baidubce.com/v2/chat/completions\",\n \"stream\": \"https://qianfan.baidubce.com/v2/chat/completions\"\n }\n },\n \"qiniu\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.qnaigc.com/v1/chat/completions\",\n \"stream\": \"https://api.qnaigc.com/v1/chat/completions\"\n }\n },\n \"qoder\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Qoder-Cli\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Qoder-Cli\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Qoder-Cli\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.qoder.com/v1/chat/completions\",\n \"stream\": \"https://api.qoder.com/v1/chat/completions\"\n }\n },\n \"qwen\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Accept-Language\": \"*\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Connection\": \"keep-alive\",\n \"Content-Type\": \"application/json\",\n \"Sec-Fetch-Mode\": \"cors\",\n \"User-Agent\": \"QwenCode/0.19.3 (<OS>; <ARCH>)\",\n \"X-Dashscope-AuthType\": \"qwen-oauth\",\n \"X-Dashscope-CacheControl\": \"enable\",\n \"X-Dashscope-UserAgent\": \"QwenCode/0.19.3 (<OS>; <ARCH>)\",\n \"X-Stainless-Arch\": \"<ARCH>\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"<OS>\",\n \"X-Stainless-Package-Version\": \"5.11.0\",\n \"X-Stainless-Retry-Count\": \"1\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"<NODE>\"\n },\n \"nonStream\": {\n \"Accept-Language\": \"*\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Connection\": \"keep-alive\",\n \"Content-Type\": \"application/json\",\n \"Sec-Fetch-Mode\": \"cors\",\n \"User-Agent\": \"QwenCode/0.19.3 (<OS>; <ARCH>)\",\n \"X-Dashscope-AuthType\": \"qwen-oauth\",\n \"X-Dashscope-CacheControl\": \"enable\",\n \"X-Dashscope-UserAgent\": \"QwenCode/0.19.3 (<OS>; <ARCH>)\",\n \"X-Stainless-Arch\": \"<ARCH>\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"<OS>\",\n \"X-Stainless-Package-Version\": \"5.11.0\",\n \"X-Stainless-Retry-Count\": \"1\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"<NODE>\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Accept-Language\": \"*\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Connection\": \"keep-alive\",\n \"Content-Type\": \"application/json\",\n \"Sec-Fetch-Mode\": \"cors\",\n \"User-Agent\": \"QwenCode/0.19.3 (<OS>; <ARCH>)\",\n \"X-Dashscope-AuthType\": \"qwen-oauth\",\n \"X-Dashscope-CacheControl\": \"enable\",\n \"X-Dashscope-UserAgent\": \"QwenCode/0.19.3 (<OS>; <ARCH>)\",\n \"X-Stainless-Arch\": \"<ARCH>\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"<OS>\",\n \"X-Stainless-Package-Version\": \"5.11.0\",\n \"X-Stainless-Retry-Count\": \"1\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"<NODE>\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chat.qwen.ai/api/v1/services/aigc/text-generation/generation\",\n \"stream\": \"https://chat.qwen.ai/api/v1/services/aigc/text-generation/generation\"\n }\n },\n \"qwen-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chat.qwen.ai/api/v2/chat/completions\",\n \"stream\": \"https://chat.qwen.ai/api/v2/chat/completions\"\n }\n },\n \"reka\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.reka.ai/v1/chat/completions\",\n \"stream\": \"https://api.reka.ai/v1/chat/completions\"\n }\n },\n \"requesty\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://router.requesty.ai/v1/chat/completions\",\n \"stream\": \"https://router.requesty.ai/v1/chat/completions\"\n }\n },\n \"sambanova\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.sambanova.ai/v1/chat/completions\",\n \"stream\": \"https://api.sambanova.ai/v1/chat/completions\"\n }\n },\n \"scaleway\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.scaleway.ai/v1/chat/completions\",\n \"stream\": \"https://api.scaleway.ai/v1/chat/completions\"\n }\n },\n \"sensenova\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://token.sensenova.cn/v1/chat/completions\",\n \"stream\": \"https://token.sensenova.cn/v1/chat/completions\"\n }\n },\n \"siliconflow\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.siliconflow.com/v1/chat/completions\",\n \"stream\": \"https://api.siliconflow.com/v1/chat/completions\"\n }\n },\n \"snowflake\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://{account}.snowflakecomputing.com/api/v2\",\n \"stream\": \"https://{account}.snowflakecomputing.com/api/v2\"\n }\n },\n \"sparkdesk\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://spark-api.xf-yun.com/v3.1/chat/completions\",\n \"stream\": \"https://spark-api.xf-yun.com/v3.1/chat/completions\"\n }\n },\n \"stepfun\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.stepfun.com/v1/chat/completions\",\n \"stream\": \"https://api.stepfun.com/v1/chat/completions\"\n }\n },\n \"sumopod\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ai.sumopod.com/v1/chat/completions\",\n \"stream\": \"https://ai.sumopod.com/v1/chat/completions\"\n }\n },\n \"suno\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://studio-api.suno.ai/api/generate/v2/\",\n \"stream\": \"https://studio-api.suno.ai/api/generate/v2/\"\n }\n },\n \"synthetic\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.synthetic.new/openai/v1/chat/completions\",\n \"stream\": \"https://api.synthetic.new/openai/v1/chat/completions\"\n }\n },\n \"t3-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://t3.chat/api/chat\",\n \"stream\": \"https://t3.chat/api/chat\"\n }\n },\n \"tencent\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.hunyuan.cloud.tencent.com/v1/chat/completions\",\n \"stream\": \"https://api.hunyuan.cloud.tencent.com/v1/chat/completions\"\n }\n },\n \"theoldllm\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://theoldllm.vercel.app/api/chatgpt\",\n \"stream\": \"https://theoldllm.vercel.app/api/chatgpt\"\n }\n },\n \"together\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.together.xyz/v1/chat/completions\",\n \"stream\": \"https://api.together.xyz/v1/chat/completions\"\n }\n },\n \"tokenrouter\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.tokenrouter.com/v1/chat/completions\",\n \"stream\": \"https://api.tokenrouter.com/v1/chat/completions\"\n }\n },\n \"trae\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://core-normal.trae.ai/api/remote/v1\",\n \"stream\": \"https://core-normal.trae.ai/api/remote/v1\"\n }\n },\n \"udio\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://www.udio.com/api/generate-proxy\",\n \"stream\": \"https://www.udio.com/api/generate-proxy\"\n }\n },\n \"uncloseai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://hermes.ai.unturf.com/v1/chat/completions\",\n \"stream\": \"https://hermes.ai.unturf.com/v1/chat/completions\"\n }\n },\n \"upstage\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.upstage.ai/v1/chat/completions\",\n \"stream\": \"https://api.upstage.ai/v1/chat/completions\"\n }\n },\n \"v0-vercel\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.v0.dev/v1/chat/completions\",\n \"stream\": \"https://api.v0.dev/v1/chat/completions\"\n }\n },\n \"venice\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.venice.ai/api/v1/chat/completions\",\n \"stream\": \"https://api.venice.ai/api/v1/chat/completions\"\n }\n },\n \"veoaifree-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://veoaifree.com/wp-admin/admin-ajax.php\",\n \"stream\": \"https://veoaifree.com/wp-admin/admin-ajax.php\"\n }\n },\n \"vercel-ai-gateway\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ai-gateway.vercel.sh/v1/chat/completions\",\n \"stream\": \"https://ai-gateway.vercel.sh/v1/chat/completions\"\n }\n },\n \"vertex\": {\n \"format\": \"gemini\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://generativelanguage.googleapis.com/v1beta/models/test-model:generateContent\",\n \"stream\": \"https://generativelanguage.googleapis.com/v1beta/models/test-model:streamGenerateContent?alt=sse\"\n }\n },\n \"vertex-partner\": {\n \"format\": \"gemini\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://us-central1-aiplatform.googleapis.com/v1/projects\",\n \"stream\": \"https://us-central1-aiplatform.googleapis.com/v1/projects\"\n }\n },\n \"volcengine\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\",\n \"stream\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\"\n }\n },\n \"wafer\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://pass.wafer.ai/v1/messages\",\n \"stream\": \"https://pass.wafer.ai/v1/messages\"\n }\n },\n \"wandb\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.inference.wandb.ai/v1/chat/completions\",\n \"stream\": \"https://api.inference.wandb.ai/v1/chat/completions\"\n }\n },\n \"windsurf\": {\n \"format\": \"windsurf\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://server.self-serve.windsurf.com\",\n \"stream\": \"https://server.self-serve.windsurf.com\"\n }\n },\n \"x5lab\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.x5lab.dev/v1/chat/completions\",\n \"stream\": \"https://api.x5lab.dev/v1/chat/completions\"\n }\n },\n \"xai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.x.ai/v1/chat/completions\",\n \"stream\": \"https://api.x.ai/v1/chat/completions\"\n }\n },\n \"xiaomi-mimo\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.xiaomimimo.com/v1\",\n \"stream\": \"https://api.xiaomimimo.com/v1\"\n }\n },\n \"yi\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.lingyiwanwu.com/v1/chat/completions\",\n \"stream\": \"https://api.lingyiwanwu.com/v1/chat/completions\"\n }\n },\n \"yuanbao-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://yuanbao.tencent.com/api/chat\",\n \"stream\": \"https://yuanbao.tencent.com/api/chat\"\n }\n },\n \"zai\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"<CRED>\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.z.ai/api/anthropic/v1/messages?beta=true\",\n \"stream\": \"https://api.z.ai/api/anthropic/v1/messages?beta=true\"\n }\n },\n \"zai-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chat.z.ai\",\n \"stream\": \"https://chat.z.ai\"\n }\n },\n \"zed-hosted\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://cloud.zed.dev/completions\",\n \"stream\": \"https://cloud.zed.dev/completions\"\n }\n },\n \"zenmux\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://zenmux.ai/api/v1/chat/completions\",\n \"stream\": \"https://zenmux.ai/api/v1/chat/completions\"\n }\n },\n \"zenmux-free\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer <TOK>\",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://zenmux.ai/api/anthropic/v1/messages\",\n \"stream\": \"https://zenmux.ai/api/anthropic/v1/messages\"\n }\n }\n}\n"}}, "docs/i18n/cs/README.md": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785746454.5157194, "n": 112445, "h": "d41719d36550c571", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.svg\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.svg\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.svg\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Pass `--allow-build` at install time to enable native build scripts required by `better-sqlite3` and `@swc/core` (the `approve-builds -g` command is not supported for global installs on pnpm v11):\n>\n> ```bash\n> pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "1bda6c15dc885b645243f6cc198688ba6bb7480c": {"t": 1785764413.8358448, "n": 112445, "h": "d41719d36550c571", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.svg\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.svg\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.svg\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Pass `--allow-build` at install time to enable native build scripts required by `better-sqlite3` and `@swc/core` (the `approve-builds -g` command is not supported for global installs on pnpm v11):\n>\n> ```bash\n> pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "b729a8f27364f072c87082e03bb8e122f3d76251": {"t": 1785764415.6436114, "n": 115018, "h": "c52555adb4a1a7ac", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.svg\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.svg\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.svg\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Pass `--allow-build` at install time to enable native build scripts required by `better-sqlite3` and `@swc/core` (the `approve-builds -g` command is not supported for global installs on pnpm v11):\n>\n> ```bash\n> pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "7c23dab64de929686d2326f6824527ba9c746ca9": {"t": 1785764417.4323237, "n": 114944, "h": "5f5ffd692d374dc0", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.svg\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.svg\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.svg\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "b91ffa7f721b121876a78d552169fa10783fb076": {"t": 1785764419.9927485, "n": 118180, "h": "6a7b93caed90658d", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.svg\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.svg\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.svg\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.svg\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "54be51a664725a07e237ee6487692ad8ef5e9b79": {"t": 1785764421.7236533, "n": 118180, "h": "3e0d9d5b90c20cc1", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.svg\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.svg\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.svg\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.svg\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "8a1d9beb55fe825bd132c8696117046258869a79": {"t": 1785764423.7960794, "n": 118547, "h": "193e9c035bc06fa6", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.svg\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.svg\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.svg\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.svg\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "3d75fb3fae6eb50f8d2ae5e678dfdc2978e33163": {"t": 1785764425.701589, "n": 118300, "h": "648861745370d537", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.svg\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.svg\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.svg\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.svg\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "5b8e41c1b2a4ef0412f8002fd3909ea7e10efd1b": {"t": 1785764427.4826927, "n": 118300, "h": "a71825816c457a07", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "7388623244b0e75f528f9a2d0983bda027bc053a": {"t": 1785764429.31307, "n": 118300, "h": "cd5c2dad2c12be8a", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "cde6f560140ff86aa3ffbec72282e31cfcba04cd": {"t": 1785764432.5278122, "n": 117089, "h": "be1d684d6e1e0924", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Settings-Driven Lock Hierarchy** — Provider profiles control default account/model lockouts, global model quarantine, and provider circuit breakers from one control surface, while explicit upstream `Retry-After` windows still take priority\n- **Exponential Backoff** — Progressive retry delays for both account/model lockouts and higher-level quarantine\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| 🔄 **Cooldown-Aware Retries** | Chat requests auto-retry on model-scoped cooldowns with configurable `requestRetry` and `maxRetryIntervalSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | --------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-provider and per-model trip/recover with 10-minute cooldowns |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| 🔄 **Cooldown-Aware Retries** 🆕 | Auto-retry chat on model cooldowns; configurable `requestRetry` / `maxRetryIntervalSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "333f0b9f2d19e61cc3108cd66bd1f30622a25c2a": {"t": 1785764436.5259306, "n": 117090, "h": "41c28b5cef34c20d", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)\n\n---\n\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Settings-Driven Lock Hierarchy** — Provider profiles control default account/model lockouts, global model quarantine, and provider circuit breakers from one control surface, while explicit upstream `Retry-After` windows still take priority\n- **Exponential Backoff** — Progressive retry delays for both account/model lockouts and higher-level quarantine\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| 🔄 **Cooldown-Aware Retries** | Chat requests auto-retry on model-scoped cooldowns with configurable `requestRetry` and `maxRetryIntervalSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | --------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-provider and per-model trip/recover with 10-minute cooldowns |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| 🔄 **Cooldown-Aware Retries** 🆕 | Auto-retry chat on model cooldowns; configurable `requestRetry` / `maxRetryIntervalSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "e5c4e450c0cd597c2de3d9dde1d74b572c0a6bb3": {"t": 1785764438.1935754, "n": 116868, "h": "329c73205017133c", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Settings-Driven Lock Hierarchy** — Provider profiles control default account/model lockouts, global model quarantine, and provider circuit breakers from one control surface, while explicit upstream `Retry-After` windows still take priority\n- **Exponential Backoff** — Progressive retry delays for both account/model lockouts and higher-level quarantine\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| 🔄 **Cooldown-Aware Retries** | Chat requests auto-retry on model-scoped cooldowns with configurable `requestRetry` and `maxRetryIntervalSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | --------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| 🔄 **Cooldown-Aware Retries** 🆕 | Auto-retry chat on model cooldowns; configurable `requestRetry` / `maxRetryIntervalSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "9e45baae58644a3001b6d1012a461e7f5726184b": {"t": 1785764439.927704, "n": 115599, "h": "e7a87bfcf523e187", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Settings-Driven Lock Hierarchy** — Provider profiles control default account/model lockouts, global model quarantine, and provider circuit breakers from one control surface, while explicit upstream `Retry-After` windows still take priority\n- **Exponential Backoff** — Progressive retry delays for both account/model lockouts and higher-level quarantine\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** — Persistent logs that survive server restarts\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** — App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| 🔄 **Cooldown-Aware Retries** | Chat requests auto-retry on model-scoped cooldowns with configurable `requestRetry` and `maxRetryIntervalSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | --------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| 🔄 **Cooldown-Aware Retries** 🆕 | Auto-retry chat on model cooldowns; configurable `requestRetry` / `maxRetryIntervalSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "86fc7841b89371eb813a00922bc526662ab3bad6": {"t": 1785764442.4027174, "n": 108963, "h": "23a9e40aba54bab9", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** — Progressive retry delays\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** — Persistent logs that survive server restarts\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** — App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.5 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.5.5 Highlights (Apr 2026)\n\n| Feature | What It Does |\n| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| 🔗 **Context Relay Strategy** | New combo strategy that preserves session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config — no more bypass in restricted envs |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner with instructions |\n| 📎 **Gemini PDF Attachments** | PDF files attached in chat messages are now correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ----------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "87c82071c0c514831e549fc2e9ac7306708a017d": {"t": 1785764444.5941145, "n": 108760, "h": "30560fd73dc7dad1", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)\n\n---\n\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** — Progressive retry delays\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 60+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** — Persistent logs that survive server restarts\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** — App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| --- | --- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.5 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.5.5 Highlights (Apr 2026)\n\n| Feature | What It Does |\n| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| 🔗 **Context Relay Strategy** | New combo strategy that preserves session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config — no more bypass in restricted envs |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner with instructions |\n| 📎 **Gemini PDF Attachments** | PDF files attached in chat messages are now correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ----------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "1442c47bbb68383fc4a1c7295898cc8823d37274": {"t": 1785764446.3066685, "n": 108110, "h": "b1503eadf726a19c", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** — Progressive retry delays\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 60+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** — Persistent logs that survive server restarts\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** — App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.5 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.5.5 Highlights (Apr 2026)\n\n| Feature | What It Does |\n| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| 🔗 **Context Relay Strategy** | New combo strategy that preserves session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config — no more bypass in restricted envs |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner with instructions |\n| 📎 **Gemini PDF Attachments** | PDF files attached in chat messages are now correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ----------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "581ff5fc73df3de6f3577f993735a3ea5692d757": {"t": 1785764448.4087706, "n": 108160, "h": "ba525ca7a76c4fd9", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)\n\n---\n\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** — Progressive retry delays\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 60+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** — Persistent logs that survive server restarts\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** — App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport LOG_TO_FILE=\"${LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.5 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.5.5 Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| 🔗 **Context Relay Strategy** | New combo strategy that preserves session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config — no more bypass in restricted envs |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner with instructions |\n| 📎 **Gemini PDF Attachments** | PDF files attached in chat messages are now correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ---------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md)| Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "5085dcf96f72bc3ddaf7ac4473bbf9dba31e340b": {"t": 1785764450.11344, "n": 111940, "h": "55b876e65b1b0a21", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Váš univerzální API proxy – jeden koncový bod, 60+ poskytovatelů, nulové prostoje. Nyní s**MCP Server (25 nástrojů)**,**Protokol A2A**,**Paměť/Skills Systems**a**Electron Desktop App**._\n\n**Dokončení chatu • Vložení • Generování obrázků • Video • Hudba • Zvuk • Změna pořadí •**Vyhledávání na webu**• Server MCP • Protokol A2A • 100% TypeScript**---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 Web](https://omniroute.online) • [🚀 Rychlý start](#-rychlý start) • [💡 Funkce](#-klíčových-funkcí) • [📖 Dokumenty](#-dokumentace) • [💰 Cena](#-cena-na první pohled) • [🬒 WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)</div>\n\n🌐**Dostupné v:**🇺🇸 [anglicky](README.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsk](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [Maďarština](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 (Portugalsko)](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)---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<podrobnosti>\n<summary><b>Kliknutím zobrazíte snímky obrazovky řídicího panelu</b></summary>\n\n| Strana | Snímek obrazovky |\n| --------------------- | --------------------------------------------------- | ---------- |\n| **Poskytovatelé** | ![Poskytovatelé](docs/screenshots/01-providers.png) |\n| **Komba** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Zdraví** | ![Zdraví](docs/screenshots/04-health.png) |\n| **Překladatel** | ![Translator](docs/screenshots/05-translator.png) |\n| **Nastavení** | ![Nastavení](docs/screenshots/06-settings.png) |\n| **Nástroje CLI** | ![Nástroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly použití** | ![Použití](docs/screenshots/08-usage.png) |\n| **Koncové body** | ![Koncové body](docs/screenshots/09-endpoint.png) | </details> |\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Připojte jakýkoli nástroj IDE nebo CLI s umělou inteligencí prostřednictvím OmniRoute – bezplatné brány API pro neomezené kódování._\n\n <tabulka>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205 000</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20,9 000</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14,6 000</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9,9 000</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"Železný dráp\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2,1 000</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106 000</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60,8 000</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Kód Claude\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67,3 000</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94,7 000</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilokód\" width=\"48\"/><br/>\n <b>Kilový kód</b>\n </a><br/>\n <sub>⭐ 15,5 000</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 Všichni agenti se připojují přes <code>http://localhost:20128/v1</code> nebo <code>http://cloud.omniroute.online/v1</code> — jedna konfigurace, neomezené modely a kvóta</sub>---\n\n## 🤔 Why OmniRoute?\n\n**Přestaňte plýtvat penězi a narážet na limity:**\n\n– <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Kvóta předplatného vyprší nevyužita každý měsíc\n– <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Omezení sazby vám brání uprostřed kódování\n– <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Drahá rozhraní API (20–50 $ měsíčně na poskytovatele)\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Ruční přepínání mezi poskytovateli\n\n**OmniRoute to řeší:**\n\n- ✅**Maximalizujte odběry**- Sledujte kvótu, před resetováním použijte každý bit\n- ✅**Automatická záloha**- Předplatné → Klíč API → Levné → Zdarma, nulové prostoje\n- ✅**Více účtů**- Round-robin mezi účty na poskytovatele\n- ✅**Universal**- Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, jakýmkoliv nástrojem CLI---\n\n## 📧 Support\n\n> 💬**Připojte se k naší komunitě!**[Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získejte nápovědu, sdílejte tipy a buďte v obraze.\n\n-**Web**: [omniroute.online](https://omniroute.online) -**GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) -**Problémy**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**WhatsApp**: [Skupina komunity](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) -**Přispívání**: Podívejte se na [CONTRIBUTING.md](CONTRIBUTING.md), otevřete PR nebo si vyberte „dobré první číslo“ -**Původní projekt**: [9router by decolua](https://github.com/decolua/9router)### 🐛 Reporting a Bug?\n\nPři otevírání problému spusťte příkaz system-info a připojte vygenerovaný soubor:```bash\nnpm run system-info\n\n```\n\nTím se vygeneruje soubor `system-info.txt` s vaší verzí Node.js, verzí OmniRoute, podrobnostmi OS, nainstalovanými nástroji CLI (qoder, gemini, claude, codex, antigravity, droid atd.), stavem Docker/PM2 a systémovými balíčky – vše, co potřebujeme k rychlé reprodukci vašeho problému. Připojte soubor přímo k vašemu problému na GitHubu.---\n\n## 🔄 How It Works\n\n```\n\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n│ http://localhost:20128/v1\n↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n│\n├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n│ ↓ quota exhausted\n├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n│ ↓ budget limit\n├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n│ ↓ budget limit\n└─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n\n````\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n>**Každý vývojář používající nástroje AI čelí těmto problémům denně.**OmniRoute byl vytvořen tak, aby je vyřešil všechny – od překročení nákladů po regionální bloky, od přerušených toků OAuth po operace protokolů a podniková pozorovatelnost.\n\n<podrobnosti>\n<summary><b>💸 1. „Platím za drahé předplatné, ale stále mě vyrušují limity“</b></summary>\n\nVývojáři platí 20–200 $ měsíčně za Claude Pro, Codex Pro nebo GitHub Copilot. I při placení má kvóta strop – 5 hodin používání, týdenní limity nebo limity sazby za minutu. Uprostřed relace kódování poskytovatel přestane reagovat a vývojář ztrácí tok a produktivitu.\n\n**Jak to řeší OmniRoute:**\n\n-**Chytrý 4-úrovňový záložní zdroj**– Pokud dojde k vyčerpání kvóty předplatného, automaticky se přesměruje na klíč API → Levné → Zdarma s nulovým ručním zásahem\n-**Sledování limitů poskytovatele**– Snímky kvót v mezipaměti se obnovují podle plánu na straně serveru (výchozí `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) s možností ručního obnovení v uživatelském rozhraní\n–**Podpora více účtů**– Více účtů na poskytovatele s automatickým opakováním – když jeden dojde, přepne se na další\n-**Vlastní komba**– Přizpůsobitelné záložní řetězce s 9 strategiemi vyvažování (prioritní, vážená, na prvním místě, s cyklem, P2C, náhodná, nejméně používaná, nákladově optimalizovaná, striktně náhodná)\n-**Codex Business Quotas**— Sledování kvót Business/Tým pracovního prostoru přímo na řídicím panelu</details>\n\n<podrobnosti>\n<summary><b>🔌 2. „Potřebuji používat více poskytovatelů, ale každý má jiné API“</b></summary>\n\nOpenAI používá jeden formát, Claude (Anthropic) jiný a Gemini ještě jiný. Pokud chce vývojář testovat modely od různých poskytovatelů nebo mezi nimi couvnout, musí překonfigurovat sady SDK, změnit koncové body, vypořádat se s nekompatibilními formáty. Vlastní poskytovatelé (FriendLI, NIM) mají nestandardní koncové body modelu.\n\n**Jak to řeší OmniRoute:**\n\n-**Unified Endpoint**– Jediný `http://localhost:20128/v1` slouží jako proxy pro všech 60+ poskytovatelů\n-**Formátový překlad**— Automatický a transparentní: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n-**Response Sanitization**– Odstraňuje nestandardní pole (`x_groq`, `usage_breakdown`, `service_tier`), která porušují OpenAI SDK v1.83+\n-**Normalizace rolí**— Převádí `vývojář` → `systém` pro poskytovatele, kteří nejsou OpenAI; `systém` → `uživatel` pro GLM/ERNIE\n–**Think Tag Extraction**– Extrahuje bloky „<think>“ z modelů jako DeepSeek R1 do standardizovaného „reasoning_content“\n-**Strukturovaný výstup pro Gemini**— `json_schema` → automatický převod `responseMimeType`/`responseSchema`\n-**`stream` má výchozí hodnotu `false`**— Vyhovuje specifikaci OpenAI a zabraňuje neočekávanému SSE v sadách Python/Rust/Go SDK</details>\n\n<podrobnosti>\n<summary><b>🌐 3. „Můj poskytovatel umělé inteligence blokuje můj region/země“</b></summary>\n\nPoskytovatelé jako OpenAI/Codex blokují přístup z určitých geografických oblastí. Během připojení OAuth a rozhraní API se uživatelům zobrazují chyby jako „unsupported_country_region_territory“. To je frustrující zejména pro vývojáře z rozvojových zemí.\n\n**Jak to řeší OmniRoute:**\n\n–**3úrovňová konfigurace proxy**– konfigurovatelný proxy na 3 úrovních: globální (veškerý provoz), podle poskytovatele (pouze jeden poskytovatel) a podle připojení/klíče\n-**Barevně kódované odznaky proxy**— Vizuální indikátory: 🢢 globální proxy, 🟡 proxy poskytovatele, 🔵 proxy připojení, vždy zobrazující IP\n-**Výměna tokenů OAuth přes proxy**– tok OAuth prochází také přes proxy a řeší se `unsupported_country_region_territory`\n-**Testy připojení přes proxy**— Testy připojení používají nakonfigurovaný proxy (už žádné přímé obcházení)\n-**Podpora SOCKS5**— Plná podpora proxy SOCKS5 pro odchozí směrování\n-**TLS Fingerprint Spoofing**– TLS otisk prstu podobný prohlížeči přes `wreq-js` k obejití detekce botů\n-**🔏 CLI Fingerprint Matching**– Změní pořadí hlaviček a polí těla tak, aby odpovídaly nativním binárním podpisům CLI, čímž se výrazně sníží riziko označení účtu. IP proxy serveru je zachována – získáte současně maskování IP maskování**a**utajení</details>\n\n<podrobnosti>\n<summary><b>🆓 4. „Chci používat AI pro kódování, ale nemám peníze“</b></summary>\n\nNe každý může platit 20–200 $ měsíčně za předplatné AI. Studenti, vývojáři z rozvíjejících se zemí, fandové a nezávislí pracovníci potřebují přístup ke kvalitním modelům za nulové náklady.\n\n**Jak to řeší OmniRoute:**\n\n-**Vestavění poskytovatelé bezplatných úrovní**— Nativní podpora pro 100% bezplatné poskytovatele: Qoder (5 neomezených modelů prostřednictvím OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezené modely: qwen3-qwender-lash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 000 tokenů/měsíc zdarma)\n-**Ollama Cloud**– modely Ollama hostované v cloudu na `api.ollama.com` s bezplatnou úrovní „Light use“; použijte předponu `ollamacloud/<model>`\n–**komba pouze zdarma**– řetězec `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/měsíc s nulovými prostoji\n-**Volný přístup NVIDIA NIM**— ~40 RPM pro vývojáře - navždy bezplatný přístup k více než 70 modelům na build.nvidia.com (přechod z kreditů na limity čisté sazby)\n-**Cost Optimized Strategy**– Strategie směrování, která automaticky vybírá nejlevnějšího dostupného poskytovatele</details>\n\n<podrobnosti>\n<summary><b>🔒 5. „Potřebuji chránit svou bránu AI před neoprávněným přístupem“</b></summary>\n\nPři vystavení brány AI do sítě (LAN, VPS, Docker) může kdokoli s adresou spotřebovat tokeny/kvótu vývojáře. Bez ochrany jsou rozhraní API zranitelná vůči zneužití, rychlému vložení a zneužití.\n\n**Jak to řeší OmniRoute:**\n\n-**Správa klíčů API**– Generování, rotace a rozsah podle poskytovatele pomocí vyhrazené stránky `/dashboard/api-manager`\n-**Oprávnění na úrovni modelu**– Omezte klíče API na konkrétní modely (`openai/*`, vzory zástupných znaků) pomocí přepínače Povolit vše/Omezit\n-**API Endpoint Protection**– Vyžadovat klíč pro `/v1/models` a blokovat konkrétní poskytovatele ze seznamu\n-**Auth Guard + ochrana CSRF**– Všechny cesty řídicího panelu chráněny middlewarem „withAuth“ + tokeny CSRF\n-**Rate Limiter**— omezení rychlosti na IP pomocí konfigurovatelných oken\n-**IP Filtering**— Seznam povolených/blokovaných pro řízení přístupu\n-**Prompt Injection Guard**– Dezinfekce proti škodlivým vzorům výzev\n-**Šifrování AES-256-GCM**— Přihlašovací údaje jsou v klidu zašifrovány</details>\n\n<podrobnosti>\n<summary><b>🛑 6. \"Můj poskytovatel selhal a ztratil jsem tok kódování\"</b></summary>\n\nPoskytovatelé umělé inteligence se mohou stát nestabilními, vracet chyby 5xx nebo narazit na dočasné limity sazeb. Pokud vývojář závisí na jediném poskytovateli, je přerušen. Bez jističů mohou opakované pokusy způsobit selhání aplikace.\n\n**Jak to řeší OmniRoute:**\n\n-**Jistič pro každý model**— Automatické otevírání/zavírání s konfigurovatelnými prahovými hodnotami a ochlazením (zavřeno/otevřeno/polootevřeno), s rozsahem pro každý model, aby se zabránilo kaskádovým blokům\n-**Exponential Backoff**— Progresivní zpoždění opakování\n-**Anti-Thundering Herd**— Mutex + semaforová ochrana proti souběžným opakovaným bouřím\n-**Combo Fallback Chains**— Pokud primární poskytovatel selže, automaticky projde řetězcem bez zásahu\n-**Combo Circuit Breaker**– Automaticky deaktivuje selhávající poskytovatele v rámci kombinovaného řetězce\n–**Health Dashboard**– Monitorování provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti, latence p50/p95/p99</details>\n\n<podrobnosti>\n<summary><b>🔧 7. „Konfigurace každého nástroje umělé inteligence je únavná a opakující se“</b></summary>\n\nVývojáři používají Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Každý nástroj potřebuje jinou konfiguraci (API endpoint, klíč, model). Překonfigurování při změně poskytovatele nebo modelu je ztráta času.\n\n**Jak to řeší OmniRoute:**\n\n-**CLI Tools Dashboard**– Vyhrazená stránka s nastavením jedním kliknutím pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n–**GitHub Copilot Config Generator**– Generuje `chatLanguageModels.json` pro kód VS s hromadným výběrem modelu\n-**Průvodce přihlášením**– Průvodce nastavením ve 4 krocích pro začínající uživatele\n–**Jeden koncový bod, všechny modely**– Jednou nakonfigurujte `http://localhost:20128/v1`, získáte přístup k více než 60 poskytovatelům</details>\n\n<podrobnosti>\n<summary><b>🔑 8. „Správa tokenů OAuth od více poskytovatelů je peklo“</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot – všechny používají OAuth 2.0 s končícími tokeny. Vývojáři se musí neustále znovu autentizovat, řešit `client_secret is missing`, `redirect_uri_mismatch` a selhání na vzdálených serverech. Zvláště problematické je OAuth na LAN/VPS.\n\n**Jak to řeší OmniRoute:**\n\n-**Automatické obnovení tokenu**– Tokeny OAuth se před vypršením platnosti obnovují na pozadí\n-**Vestavěný OAuth 2.0 (PKCE)**— Automatický tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n–**Multi-Account OAuth**– Více účtů na poskytovatele prostřednictvím extrakce tokenů JWT/ID\n-**OAuth LAN/Remote Fix**— Detekce privátní IP adresy pro `redirect_uri` + ruční režim URL pro vzdálené servery\n-**OAuth Behind Nginx**– Používá `window.location.origin` pro zpětnou kompatibilitu proxy\n–**Průvodce vzdáleným OAuth**– Podrobný průvodce pro přihlašovací údaje Google Cloud na VPS/Docker</details>\n\n<podrobnosti>\n<summary><b>📊 9. \"Nevím, kolik a kde utrácím\"</b></summary>\n\nVývojáři využívají více placených poskytovatelů, ale nemají jednotný pohled na výdaje. Každý poskytovatel má svůj vlastní panel fakturace, ale neexistuje žádné konsolidované zobrazení. Neočekávané náklady se mohou nahromadit.\n\n**Jak to řeší OmniRoute:**\n\n-**Cost Analytics Dashboard**– Sledování nákladů na token a správa rozpočtu na poskytovatele\n-**Rozpočtové limity na úroveň**– Strop útraty na úroveň, který spouští automatickou rezervu\n-**Konfigurace cen za model**– Konfigurovatelné ceny za model\n-**Statistika využití na klíč API**— Počet požadavků a naposledy použité časové razítko na klíč\n–**Panel Analytics**– Statistické karty, graf využití modelu, tabulka poskytovatelů s mírou úspěšnosti a latencí</details>\n\n<podrobnosti>\n<summary><b>🐛 10. „Nemohu diagnostikovat chyby a problémy ve voláních AI“</b></summary>\n\nKdyž se volání nezdaří, vývojář neví, zda to byl limit sazby, vypršela platnost tokenu, nesprávný formát nebo chyba poskytovatele. Fragmentované protokoly napříč různými terminály. Bez pozorovatelnosti je ladění metodou pokus-omyl.\n\n**Jak to řeší OmniRoute:**\n\n-**Sjednocený panel protokolů**– 4 karty: Protokoly požadavků, Protokoly proxy, Protokoly auditu, Konzole\n-**Console Log Viewer**— Prohlížeč ve stylu terminálu v reálném čase s barevně odlišenými úrovněmi, automatickým posouváním, vyhledáváním, filtrem\n-**Protokoly SQLite Proxy**— Trvalé protokoly, které vydrží restartování serveru\n-**Translator Playground**— 4 režimy ladění: Playground (překlad formátu), Tester chatu (zpáteční), Test Bench (dávka), Live Monitor (v reálném čase)\n–**Požadavek na telemetrii**– latence p50/p95/p99 + sledování X-Request-Id\n-**Protokolování založené na souborech s rotací**– Protokoly aplikací se střídají podle velikosti, dnů uchování a počtu archivů; Artefakty protokolu hovorů rotují podle dnů uchování a počtu souborů\n-**System Info Report**— `npm run system-info` vygeneruje `system-info.txt` s vaším úplným prostředím (verze uzlu, verze OmniRoute, OS, nástroje CLI, stav Docker/PM2). Připojte jej při hlášení problémů pro okamžité třídění.</details>\n\n<podrobnosti>\n<summary><b>🏗️ 11. „Nasazení a údržba brány je složitá“</b></summary>\n\nInstalace, konfigurace a údržba AI proxy v různých prostředích (místní, VPS, Docker, cloud) je náročná na práci. Problémy jako pevně zakódované cesty, „EACCES“ v adresářích, konflikty portů a sestavení napříč platformami zvyšují tření.\n\n**Jak to řeší OmniRoute:**\n\n-**Globální instalace npm**– `npm install -g omniroute && omniroute` – hotovo\n-**Docker Multi-Platform**– nativní AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n-**Docker Compose Profiles**– `base` (žádné nástroje CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n-**Electron Desktop App**– nativní aplikace pro Windows/macOS/Linux se systémovou lištou, automatickým spuštěním, offline režimem\n-**Split-Port Mode**– API a Dashboard na samostatných portech pro pokročilé scénáře (reverzní proxy, kontejnerová síť)\n-**Cloud Sync**— Konfigurace synchronizace mezi zařízeními pomocí Cloudflare Workers\n-**DB Backups**— Automatické zálohování, obnova, export a import všech nastavení s `DISABLE_SQLITE_AUTO_BACKUP` pro externě spravované zálohy</details>\n\n<podrobnosti>\n<summary><b>🌍 12. \"Rozhraní je pouze v angličtině a můj tým nemluví anglicky\"</b></summary>\n\nTýmy v neanglicky mluvících zemích, zejména v Latinské Americe, Asii a Evropě, se potýkají s rozhraním pouze v angličtině. Jazykové bariéry snižují přijetí a zvyšují chyby konfigurace.\n\n**Jak to řeší OmniRoute:**\n\n-**Dashboard i18n — 30 jazyků**— Všech 500+ kláves přeloženo včetně arabštiny, bulharštiny, dánštiny, němčiny, španělštiny, finštiny, francouzštiny, hebrejštiny, hindštiny, maďarštiny, indonéštiny, italštiny, japonštiny, korejštiny, malajštiny, holandštiny, norštiny, polštiny, portugalštiny (PT/BR), rumunštiny, ruštiny, slovenštiny, švédštiny, thajštiny, filipínštiny, vietnamštiny, angličtiny\n-**Podpora RTL**— Podpora zprava doleva pro arabštinu a hebrejštinu\n-**Vícejazyčné README**— 30 kompletních překladů dokumentace\n-**Language Selector**— Ikona zeměkoule v záhlaví pro přepínání v reálném čase</details>\n\n<podrobnosti>\n<summary><b>🔄 13. „Potřebuji víc než jen chat – potřebuji vložení, obrázky, zvuk“</b></summary>\n\nAI není jen dokončení chatu. Vývojáři potřebují generovat obrázky, přepisovat zvuk, vytvářet vložení pro RAG, měnit hodnocení dokumentů a moderovat obsah. Každé API má jiný koncový bod a formát.\n\n**Jak to řeší OmniRoute:**\n\n-**Vložení**— `/v1/embeddings` se 6 poskytovateli a 9+ modely\n-**Generace obrázků**— `/v1/images/generations` s 10 poskytovateli a 20+ modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n-**Text-to-Video**— `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) a SD WebUI\n-**Text-to-Music**— `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n-**Audio Transscription**— `/v1/audio/transscriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n-**Text-to-Speech**— `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3,**Inworld**,**Cartesia**,**PlayHT**, + stávající poskytovatelé\n-**Moderations**— `/v1/moderations` — Kontroly bezpečnosti obsahu\n-**Přehodnocení**— `/v1/rerank` — Změna pořadí podle relevance dokumentu\n-**Responses API**— Plná podpora `/v1/responses` pro Codex</details>\n\n<podrobnosti>\n<summary><b>🧪 14. „Nemám způsob, jak testovat a porovnávat kvalitu napříč modely“</b></summary>\n\nVývojáři chtějí vědět, který model je pro jejich případ použití nejlepší – kód, překlad, uvažování – ale ruční porovnávání je pomalé. Neexistují žádné integrované nástroje eval.\n\n**Jak to řeší OmniRoute:**\n\n-**Hodnocení LLM**– Testování zlaté sady s 10 předem nahranými případy zahrnujícími pozdravy, matematiku, geografii, generování kódu, soulad s JSON, překlad, markdown, bezpečnostní odmítnutí\n-**4 strategie shody**– `přesné`, `obsahuje`, `regulární výraz`, `vlastní` (funkce JS)\n-**Testovací stolice pro překladatelské hřiště**– Dávkové testování s více vstupy a očekávanými výstupy, porovnání mezi poskytovateli\n-**Chat Tester**– Kompletní zpáteční cesta s vykreslováním vizuální odezvy\n-**Live Monitor**— Tok všech požadavků procházejících přes proxy v reálném čase</details>\n\n<podrobnosti>\n<summary><b>📈 15. „Potřebuji škálovat bez ztráty výkonu“</b></summary>\n\nJak roste objem požadavků, bez ukládání stejných otázek do mezipaměti vznikají duplicitní náklady. Bez idempotence duplikát požaduje zpracování odpadu. Musí být dodrženy limity sazeb na poskytovatele.\n\n**Jak to řeší OmniRoute:**\n\n-**Sémantická mezipaměť**– Dvouvrstvá mezipaměť (podpis + sémantická) snižuje náklady a latenci\n-**Idempotency požadavku**— 5s deduplikační okno pro identické požadavky\n–**Detekce limitu rychlosti**– RPM na poskytovatele, minimální mezera a maximální souběžné sledování\n-**Upravitelné limity rychlosti**– Konfigurovatelné výchozí hodnoty v Nastavení → Odolnost s perzistencí\n-**API Key Validation Cache**– 3vrstvá mezipaměť pro produkční výkon\n–**Health Dashboard s telemetrií**– latence p50/p95/p99, statistiky mezipaměti, doba provozu</details>\n\n<podrobnosti>\n<summary><b>🤖 16. „Chci globálně ovládat chování modelu“</b></summary>\n\nVývojáři, kteří chtějí všechny odpovědi v konkrétním jazyce, s konkrétním tónem nebo chtějí omezit tokeny uvažování. Konfigurace tohoto v každém nástroji/požadavku je nepraktická.\n\n**Jak to řeší OmniRoute:**\n\n-**System Prompt Injection**– Globální výzva aplikovaná na všechny požadavky\n-**Thinking Budget Validation**— Řízení alokace tokenů na základě požadavku (průchozí, automatické, vlastní, adaptivní)\n-**9 směrovacích strategií**— Globální strategie, které určují způsob distribuce požadavků\n-**Wildcard Router**– vzory `poskytovatel/*` se dynamicky směrují k libovolnému poskytovateli\n-**Povolit/zakázat přepínání komba**— Přepínejte komba přímo z řídicího panelu\n-**Přepnutí poskytovatele**— Povolí/zakáže všechna připojení pro poskytovatele jedním kliknutím\n–**Blokovaní poskytovatelé**– vyloučení konkrétních poskytovatelů ze seznamu `/v1/models`</details>\n\n<podrobnosti>\n<summary><b>🧰 17. „Potřebuji nástroje MCP jako prvotřídní možnosti produktu“</b></summary>\n\nMnoho bran AI odhaluje MCP pouze jako skrytý detail implementace. Týmy potřebují viditelnou a spravovatelnou provozní vrstvu.\n\n**Jak to řeší OmniRoute:**\n\n- MCP se objeví na navigačním panelu a na kartě protokolu koncového bodu\n- Vyhrazená stránka správy MCP s procesem, nástroji, rozsahy a auditem\n- Vestavěný rychlý start pro `omniroute --mcp` a přihlášení klienta</details>\n\n<podrobnosti>\n<summary><b>🧠 18. „Potřebuji orchestraci A2A s cestami synchronizace + streamování“</b></summary>\n\nPracovní postupy agentů vyžadují jak přímé odpovědi, tak dlouhotrvající streamované spouštění s řízením životního cyklu.\n\n**Jak to řeší OmniRoute:**\n\n– Koncový bod A2A JSON-RPC (`POST /a2a`) s `zprávou/odeslat` a `zprávou/streamem`\n- SSE streamování s šířením koncového stavu\n- Rozhraní API životního cyklu úloh pro `tasks/get` a `tasks/cancel`</details>\n\n<podrobnosti>\n<summary><b>🛰️ 19. „Potřebuji skutečný stav procesu MCP, nikoli odhadovaný stav“</b></summary>\n\nOperační týmy potřebují vědět, zda je MCP skutečně naživu, nejen zda je API dosažitelné.\n\n**Jak to řeší OmniRoute:**\n\n- Soubor srdečního tepu za běhu s PID, časovými razítky, transportem, počtem nástrojů a režimem rozsahu\n- Stavové API MCP kombinující srdeční tep + nedávnou aktivitu\n- Stavové karty uživatelského rozhraní pro aktuálnost procesu / provozuschopnosti / srdečního tepu</details>\n\n<podrobnosti>\n<summary><b>📋 20. „Potřebuji provádění auditovatelného nástroje MCP“</b></summary>\n\nKdyž nástroje mutují konfiguraci nebo spouštějí operace operací, týmy potřebují forenzní sledovatelnost.\n\n**Jak to řeší OmniRoute:**\n\n- Protokolování auditu podporované SQLite pro volání nástrojů MCP\n- Filtry podle nástroje, úspěchu/neúspěchu, klíče API a stránkování\n- Tabulka auditu řídicího panelu + statistiky koncových bodů pro automatizaci</details>\n\n<podrobnosti>\n<summary><b>🔐 21. „Potřebuji omezená oprávnění MCP na integraci“</b></summary>\n\nRůzní klienti by měli mít nejméně privilegovaný přístup ke kategoriím nástrojů.\n\n**Jak to řeší OmniRoute:**\n\n- 10 granulárních rozsahů MCP pro řízený přístup k nástrojům\n- Vynucení rozsahu a viditelnost v uživatelském rozhraní správy MCP\n- Bezpečná výchozí poloha pro provozní nástroje</details>\n\n<podrobnosti>\n<summary><b>⚙️ 22. „Potřebuji provozní kontroly bez přerozdělování“</b></summary>\n\nTýmy potřebují rychlé změny běhového prostředí během incidentů nebo nákladových událostí.\n\n**Jak to řeší OmniRoute:**\n\n- Aktivace kombinace přepínačů přímo z řídicího panelu MCP\n- Použijte profily odolnosti z předdefinovaných balíčků zásad\n- Resetujte stav jističe ze stejného ovládacího panelu</details>\n\n<podrobnosti>\n<summary><b>🔄 23. „Potřebuji živou viditelnost a zrušení životního cyklu úkolu A2A“</b></summary>\n\nBez viditelnosti životního cyklu je obtížné třídit incidenty úkolů.\n\n**Jak to řeší OmniRoute:**\n\n- Seznam úkolů / filtrování podle stavu / dovedností se stránkováním\n- Podrobnější informace o metadatech úkolů, událostech a artefaktech\n- Koncový bod zrušení úlohy a akce uživatelského rozhraní s potvrzením</details>\n\n<podrobnosti>\n<summary><b>🌊 24. „Potřebuji aktivní metriky streamu pro zatížení A2A“</b></summary>\n\nStreamovací pracovní postupy vyžadují provozní přehled o souběžných a živých připojeních.\n\n**Jak to řeší OmniRoute:**\n\n- Aktivní čítače toku integrované do stavu A2A\n- Časové razítko posledního úkolu a počty za stav\n- Karty palubní desky A2A pro monitorování operací v reálném čase</details>\n\n<podrobnosti>\n<summary><b>🪪 25. „Potřebuji pro klienty zjišťování standardních agentů“</b></summary>\n\nExterní klienti a orchestrátoři potřebují strojově čitelná metadata pro integraci.\n\n**Jak to řeší OmniRoute:**\n\n- Karta agenta vystavena na adrese `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazené v uživatelském rozhraní pro správu\n- A2A status API obsahuje metadata zjišťování pro automatizaci</details>\n\n<podrobnosti>\n<summary><b>🧭 26. „Potřebuji zjistitelnost protokolu v uživatelském rozhraní produktu“</b></summary>\n\nPokud uživatelé nemohou objevit protokolové povrchy, kvalita přijetí a podpory klesá.\n\n**Jak to řeší OmniRoute:**\n\n– Konsolidovaná stránka**Koncové body**s kartami pro koncové body proxy, MCP, A2A a API\n- Přepínání stavu inline služby (Online/Offline) pro MCP a A2A\n- Odkazy z přehledu na vyhrazené karty správy</details>\n\n<podrobnosti>\n<summary><b>🧪 27. „Potřebuji komplexní ověření protokolu se skutečnými klienty“</b></summary>\n\nFalešné testy nestačí k ověření kompatibility protokolu před vydáním.\n\n**Jak to řeší OmniRoute:**\n\n- Sada E2E, která spouští aplikaci a používá skutečný přenos klienta MCP SDK\n- Klient A2A testuje toky zjišťování, odesílání, streamování, získávání a rušení\n- Křížová kontrola tvrzení proti auditu MCP a API úloh A2A</details>\n\n<podrobnosti>\n<summary><b>📡 28. „Potřebuji jednotnou pozorovatelnost napříč všemi rozhraními“</b></summary>\n\nRozdělení pozorovatelnosti protokolem vytváří slepá místa a delší MTTR.\n\n**Jak to řeší OmniRoute:**\n\n- Sjednocené dashboardy/logy/analýzy v jednom produktu\n- Zdraví + audit + telemetrie požadavků napříč vrstvami OpenAI, MCP a A2A\n- Provozní API pro stav a automatizaci</details>\n\n<podrobnosti>\n<summary><b>💼 29. \"Potřebuji jeden runtime pro proxy + nástroje + orchestraci agenta\"</b></summary>\n\nProvozování mnoha samostatných služeb zvyšuje provozní náklady a způsoby selhání.\n\n**Jak to řeší OmniRoute:**\n\n- Proxy, MCP server a A2A server v jednom zásobníku kompatibilní s OpenAI\n- Sdílená autentizace, odolnost, úložiště dat a pozorovatelnost\n- Konzistentní model politiky na všech interakčních plochách</details>\n\n<podrobnosti>\n<summary><b>🚀 30. „Potřebuji odeslat agentské pracovní postupy bez rozšiřování kódu lepidla“</b></summary>\n\nTýmy ztrácejí rychlost při spojování více ad-hoc služeb a skriptů.\n\n**Jak to řeší OmniRoute:**\n\n- Jednotná strategie koncových bodů pro klienty a agenty\n- Vestavěná uživatelská rozhraní pro správu protokolů a cesty ověřování kouře\n- Základy připravené na výrobu (zabezpečení, protokolování, odolnost, zálohování)</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Příručka A: Maximalizujte placené předplatné + levné zálohování**```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n````\n\n**Příručka B: Sada kódování s nulovými náklady**```txt\nCombo: \"free-forever\"\n\n1. gc/gemini-3-flash\n2. if/kimi-k2-thinking\n3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n\n````\n\n**Příručka C: 24/7 vždy zapnutý záložní řetězec**```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n````\n\n**Příručka D: Operace agenta s MCP + A2A**```txt\n\n1. Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2. Run A2A tasks via `message/send` and `message/stream`\n3. Observe via /dashboard/endpoint (MCP and A2A tabs)\n4. Toggle services via inline status controls\n\n````\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Nastavení kódování AI během několika minut za**$0/měsíc**. Propojte tyto bezplatné účty a použijte vestavěnou kombinaci**Free Stack**.\n\n| Krok | Akce | Poskytovatelé odemčeni |\n| ---- | --------------------------------------------------- | ------------------------------------------------------------------- |\n| 1 | Connect**Kiro**(AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 —**neomezeno**|\n| 2 | Připojte**Qoder**(Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... —**bez omezení**|\n| 3 | Připojte**Qwen**(kód zařízení) | qwen3-coder-plus, qwen3-coder-flash... —**bez omezení**|\n| 4 | Připojte**Gemini CLI**(Google OAuth) | gemini-3-flash, gemini-2.5-pro —**180 000/měsíc zdarma**|\n| 5 | `/dashboard/combos` → Šablona**Free Stack (0 $)**| Round-robin všechny bezplatné poskytovatele automaticky |\n\n**Nasměrujte libovolné IDE/CLI na:**`http://localhost:20128/v1` · Klíč API: `any-string` · Hotovo.\n\n>**Volitelné dodatečné pokrytí (také zdarma):**Klíč Groq API (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelů), Cerebras (1 M token/den), LongCat API klíč (50 M tokenů/den!), Cloudflare Workers AI (10 000 neuronů/den, 50+ modelů).## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n````\n\n> **Uživatelé pnpm:**Po instalaci spusťte příkaz `pnpm accept-builds -g`, abyste povolili nativní skripty sestavení vyžadované `better-sqlite3` a `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm schválit-builds -g # Vybrat všechny balíčky → schválit\n> omniroute\n> ```\n\nDashboard se otevře na adrese `http://localhost:20128` a základní adresa URL API je `http://localhost:20128/v1`.\n\n| Příkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------ |\n| \"všestranná cesta\" | Spustit server (`PORT=20128`, API a řídicí panel na stejném portu) |\n| `omniroute --port 3000` | Nastavte kanonický/API port na 3000 |\n| `omniroute --mcp` | Spustit MCP server (stdio transport) |\n| `omniroute --no-open` | Neotevírat automaticky prohlížeč |\n| `omniroute --help` | Zobrazit nápovědu |\n\nVolitelný režim rozděleného portu:```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n\n# API: http://localhost:20128/v1\n\n# Dashboard: http://localhost:20129\n\n````\n\n### Long-Running Streaming Timeouts\n\nPro většinu nasazení potřebujete pouze:\n\n| Proměnná | Výchozí | Účel |\n| ------------------------- | ------------------------------ | ------------------------------------------------------------- -------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | \"600 000\" | Sdílená základní linie pro upstream načítání, skryté časové limity Undici, požadavky otisků prstů TLS a časové limity požadavků/proxy mostu API |\n| `STREAM_IDLE_TIMEOUT_MS` | zdědí `REQUEST_TIMEOUT_MS` | Maximální mezera mezi streamovanými bloky, než OmniRoute přeruší stream SSE |\n\nZpětná kompatibilita je zachována: stávající `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS` a další proměnná časového limitu pro jednotlivé vrstvy stále fungují a přepisují sdílenou základní linii.\n\nPokud potřebujete jemnější ovládání, jsou k dispozici pokročilé přepisy:| Proměnná | Výchozí | Účel |\n| ----------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | zdědí `REQUEST_TIMEOUT_MS` | Celkový časový limit upstream požadavku použitý signálem přerušení hlavního načítání |\n| `FETCH_HEADERS_TIMEOUT_MS` | zdědí `FETCH_TIMEOUT_MS` | Undici časový limit pro příjem upstream hlaviček odpovědí |\n| `FETCH_BODY_TIMEOUT_MS` | zdědí `FETCH_TIMEOUT_MS` | Undici časový limit mezi upstream body těla (`0` to zakáže) |\n| `FETCH_CONNECT_TIMEOUT_MS` | \"30 000\" | Vypršel časový limit připojení Undici TCP |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | \"4000\" | Undici nečinný keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | zdědí `FETCH_TIMEOUT_MS` | Vypršel časový limit pro požadavky otisku TLS provedené prostřednictvím `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | zdědí `REQUEST_TIMEOUT_MS` nebo `30000` | Časový limit pro přesměrování proxy `/v1` z portu API na port řídicího panelu |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Časový limit příchozího požadavku na serveru API mostu |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | \"60 000\" | Časový limit příchozí hlavičky na serveru API mostu |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | \"5000\" | Udržovací časový limit na serveru API mostu |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | \"0\" | Časový limit nečinnosti soketu na serveru API mostu (`0` jej zakáže) |\n\nPokud spouštíte OmniRoute za Nginx, Caddy, Cloudflare nebo jiným reverzním proxy, ujistěte se, že proxy\nčasové limity jsou také vyšší než časové limity streamu/načtení OmniRoute.### 2) Connect providers and create your API key\n\n1. Otevřete Dashboard → `Providers` a připojte alespoň jednoho poskytovatele (OAuth nebo API klíč).\n2. Otevřete Dashboard → `Koncové body` a vytvořte klíč API.\n3. (Volitelné) Otevřete Dashboard → `Komba` a nastavte svůj záložní řetězec.### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n````\n\nPracuje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilní s OpenAI.### 4) Enable and validate protocols (v2.0)\n\n**MCP (pro operace řízené nástrojem):**```bash\nomniroute --mcp\n\n````\n\nPoté připojte svého MCP klienta přes `stdio` a otestujte nástroje jako:\n\n- `omniroute_get_health`\n- `combos_omniroute_list_combos`\n\n**A2A (pro pracovní postupy mezi agenty):**```bash\ncurl http://localhost:20128/.well-known/agent.json\n````\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ověřuje skutečné klientské toky MCP a A2A proti běžící aplikaci.### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<podrobnosti>\n<summary><b>Void Linux (šablona `xbps-src`)</b></summary>\n\nPro uživatele Void Linuxu můžete vytvořit nativní balíček pomocí `xbps-src`. Uložte tento blok jako `srcpkgs/omniroute/template`:```bash\n\n# Template file for 'omniroute'\n\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"\\_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() { # Determine target CPU arch for node-gyp\nlocal \\_gyp_arch\ncase \"$XBPS_TARGET_MACHINE\" in\naarch64*) \\_gyp_arch=arm64 ;;\narmv7*|armv6*) \\_gyp_arch=arm ;;\ni686*) \\_gyp_arch=ia32 ;;\n\\*) \\_gyp_arch=x64 ;;\nesac\n\n # 1) Install all deps – skip scripts (no network in do_build, native modules\n # compiled separately below; better-sqlite3 is serverExternalPackage so\n # Next.js does not execute it during next build)\n NODE_ENV=development npm ci --ignore-scripts\n\n # 2) Build the Next.js standalone bundle\n npm run build\n\n # 3) Copy static assets into standalone\n cp -r .next/static .next/standalone/.next/static\n [ -d public ] && cp -r public .next/standalone/public || true\n\n # 4) Compile better-sqlite3 native binding for the target architecture.\n # Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n # without npm altering them.\n local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n (cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n # 5) Place the compiled binding into the standalone bundle\n local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n mkdir -p \"$_bs3_release\"\n cp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n # 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n # so sharp is not used at runtime; x64 .so files would break aarch64 strip\n rm -rf .next/standalone/node_modules/@img\n\n # 7) Copy pino runtime deps omitted by Next.js static analysis:\n # pino-abstract-transport – required by pino's worker thread\n # split2 – dep of pino-abstract-transport\n # process-warning – dep of pino itself\n for _mod in pino-abstract-transport split2 process-warning; do\n \tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n done\n\n}\n\ndo_check() {\nnpm run test:unit\n}\n\ndo_install() {\nvmkdir usr/lib/omniroute/.next\n\n vcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n # Prevent removal of empty Next.js app router dirs by the post-install hook\n for _d in \\\n \t.next/standalone/.next/server/app/dashboard \\\n \t.next/standalone/.next/server/app/dashboard/settings \\\n \t.next/standalone/.next/server/app/dashboard/providers; do\n \ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n done\n\n cat > \"${WRKDIR}/omniroute\" <<'EOF'\n\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport LOG_TO_FILE=\"${LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\nvlicense LICENSE\n}\n\n````\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute je k dispozici jako veřejný obrázek Dockeru na [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Rychlý běh:**```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n````\n\n**Se souborem prostředí:**```bash\n\n# Copy and edit .env first\n\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n\n````\n\n**Použití Docker Compose:**```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n````\n\nPodpora řídicího panelu pro nasazení Dockeru nyní zahrnuje**Cloudflare Quick Tunnel**na jedno kliknutí na `Dashboard → Endpoints`. První povolí stahování `cloudflared` pouze v případě potřeby, spustí dočasný tunel k vašemu aktuálnímu koncovému bodu `/v1` a zobrazí vygenerovanou URL `https://*.trycloudflare.com/v1` přímo pod vaší normální veřejnou adresou URL.\n\nPoznámky:\n\n- URL Quick Tunnel jsou dočasné a mění se po každém restartu.\n- Rychlé tunely se po restartu OmniRoute nebo kontejneru automaticky neobnoví. V případě potřeby je znovu povolte z řídicího panelu.\n- Spravovaná instalace aktuálně podporuje Linux, macOS a Windows na `x64` / `arm64`.\n- Spravované rychlé tunely jsou výchozí pro přenos HTTP/2, aby se zabránilo hlučným varováním vyrovnávací paměti QUIC UDP v prostředí s omezenými kontejnery. Pokud chcete jiný přenos, nastavte `CLOUDFLARED_PROTOCOL=quic` nebo `auto`.\n- Obrazy Dockeru svazují kořeny systémové CA a předávají je spravovanému `cloudflared`, což zabraňuje selhání důvěryhodnosti TLS při zavádění tunelu uvnitř kontejneru.\n- SQLite běží v režimu WAL. `Docker stop` by mělo být povoleno dokončit, aby OmniRoute mohl zkontrolovat nejnovější změny zpět do `storage.sqlite`.\n- V přiložených souborech Compose je již nastavena doba odkladu 40 s. Pokud spouštíte obraz přímo, ponechte hodnotu `--stop-timeout 40` (nebo podobnou), aby ruční zastavení nepřerušilo čištění při vypnutí.\n- Nastavte `CLOUDFLARED_BIN=/absolutní/cesta/k/cloudflared`, pokud chcete, aby OmniRoute místo stahování používal existující binární soubor.\n\n**Použití Docker Compose s Caddy (HTTPS Auto-TLS):**\n\nOmniRoute lze bezpečně zpřístupnit pomocí automatického zřizování SSL Caddy. Ujistěte se, že záznam DNS A vaší domény ukazuje na IP adresu vašeho serveru.```yaml\nservices:\nomniroute:\nimage: diegosouzapw/omniroute:latest\ncontainer_name: omniroute\nrestart: unless-stopped\nvolumes: - omniroute-data:/app/data\nenvironment: - PORT=20128 - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\ncaddy:\nimage: caddy:latest\ncontainer_name: caddy\nrestart: unless-stopped\nports: - \"80:80\" - \"443:443\"\ncommand: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\nomniroute-data:\n\n````\n\n| Obrázek | Štítek | Velikost | Popis |\n| ------------------------- | -------- | ------ | ---------------------- |\n| `diegosouzapw/omniroute` | \"nejnovější\" | ~250 MB | Poslední stabilní verze |\n| `diegosouzapw/omniroute` | \"1.0.3\" | ~250 MB | Aktuální verze |---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕**NOVINKA!**OmniRoute je nyní k dispozici jako**nativní desktopová aplikace**pro Windows, macOS a Linux.\n\nSpusťte OmniRoute jako samostatnou desktopovou aplikaci – pro místní modely není potřeba žádný terminál, žádný prohlížeč ani internet. Aplikace založená na Electronu zahrnuje:\n\n- 🖥️**Nativní okno**— Vyhrazené okno aplikace s integrací na systémové liště\n- 🔄**Auto-Start**– Spusťte OmniRoute při přihlášení do systému\n- 🔔**Nativní oznámení**– Získejte upozornění na vyčerpání kvóty nebo problémy s poskytovatelem\n- ⚡**Instalace jedním kliknutím**— NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐**Režim offline**– Funguje plně offline s přibaleným serverem### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n````\n\n### System Tray\n\nKdyž je minimalizován, OmniRoute žije v systémové liště s rychlými akcemi:\n\n- Otevřete palubní desku\n- Změňte port serveru\n- Ukončete aplikaci\n\n📖 Úplná dokumentace: [`electron/README.md`](electron/README.md)---\n\n## 💰 Pricing at a Glance\n\n| Úroveň | Poskytovatel | Cena | Obnovení kvóty | Nejlepší pro |\n| ----------------- | --------------------------- | ------------------------------- | --------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **💳 PŘEDPLATNÉ** | Claude Code (Pro) | 20 $/měsíc | 5h + týdně | Již přihlášeno |\n| | Codex (Plus/Pro) | 20–200 USD/měsíc | 5h + týdně | Uživatelé OpenAI |\n| | Gemini CLI | **ZDARMA** | 180 tis./měsíc + 1 tis./den | Každý! |\n| | GitHub Copilot | 10–19 USD/měsíc | Měsíčně | Uživatelé GitHubu |\n| **🔑 API KEY** | NVIDIA NIM | **ZDARMA**(dev forever) | ~40 RPM | 70+ otevřených modelů |\n| | Cerebras | **ZDARMA**(1 milion toku/den) | 60 000 TPM / 30 RPM | Nejrychlejší na světě |\n| | Groq | **ZDARMA**(30 RPM) | 14,4K RPD | Ultra rychlá lama/gemma |\n| | DeepSeek V3.2 | 0,27 $ / 1,10 $ za 1 milion | Žádné | Nejlepší zdůvodnění cena/kvalita |\n| | xAI Grok-4 Fast | **0,20 $/0,50 $ za 1M**🆕 | Žádné | Nejrychlejší + volání nástroje, ultranízké |\n| | xAI Grok-4 (standardní) | 0,20 $/1,50 $ za 1M 🆕 | Žádné | Reasoning vlajková loď od xAI |\n| | Mistral | Vyzkoušení zdarma + placené | Omezená sazba | Evropská umělá inteligence |\n| | OpenRouter | Platba za použití | Žádné | 100+ modelů agr. |\n| **💰 LEVNĚ** | GLM-5 (přes Z.AI) 🆕 | 0,5 $/1 mil. | Denně 10:00 | 128K výstup, nejnovější vlajková loď |\n| | GLM-4.7 | 0,6 $/1 mil. | Denně 10:00 | Záloha rozpočtu |\n| | MiniMax M2,5 🆕 | Vstup 0,3 $/1 milion | 5hodinové válcování | Úvahy + agentské úkoly |\n| | MiniMax M2.1 | 0,2 $/1 milion | 5hodinové válcování | Nejlevnější varianta |\n| | Kimi K2.5 (Moonshot API) 🆕 | Platba za použití | Žádné | Přímý přístup Moonshot API |\n| | Kimi K2 | 9 $/měsíc byt | 10 milionů tokenů/měsíc | Předvídatelné náklady |\n| **🆓 ZDARMA** | Qoder | **$0** | Neomezené | 5 modelů neomezeně |\n| | Qwen | **$0** | Neomezené | 4 modely neomezeně |\n| | Kiro | **$0** | Neomezené | Claude Sonnet/Haiku (stavitel AWS) |\n| | LongCat Flash-Lite 🆕 | **$0**(50 milionů toku/den 🔥) | 1 RPS | Největší bezplatná kvóta na Zemi |\n| | Opylování AI 🆕 | **$0**(není potřeba žádný klíč) | 1 požadavek/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0**(10 000 neuronů/den) | ~150 resp./den | 50+ modelů, globální náskok |\n| | Scaleway AI 🆕 | **$0**(celkem 1 milion tokenů) | Omezená sazba | EU/GDPR, Qwen3 235B, Lama 70B | > 🆕**Přidané nové modely (březen 2026):**Rodina Grok-4 Fast za 0,20 $/0,50 $/M (porovnávací rychlost 1143 ms – o 30 % rychlejší než Gemini 2.5 Flash), GLM-5 přes Z.AI s výstupem 128K, aktualizovaná cena MiniMax M2.5 V5, přímé zdůvodnění Kimi K2.2 Moon. |\n\n**💡 Combo Stack 0 $ — Kompletní bezplatné nastavení:**```\n\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\n\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n\n````\n\n**Nulové náklady. Nikdy nepřestane kódovat.**Nakonfigurujte si to jako jednu kombinaci OmniRoute a všechna nouzová řešení se stanou automaticky – žádné ruční přepínání.---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> Všechny níže uvedené modely jsou**100% zdarma bez nutnosti použití kreditní karty**. OmniRoute mezi nimi automaticky směruje, když dojde jedna kvóta – zkombinujte je všechny a získáte nerozbitnou kombinaci 0 $.### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Předpona | Limit | Limit sazby |\n| -------------------- | ------ | ------------- | ---------------------- |\n| `claude-sonnet-4.5` | `kr/` |**Neomezeno**| Žádný hlášený denní limit |\n| `claude-haiku-4,5` | `kr/` |**Neomezeno**| Žádný hlášený denní limit |\n| `claude-opus-4.6` | `kr/` |**Neomezeno**| Nejnovější Opus přes Kiro |### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Předpona | Limit | Limit sazby |\n| ------------------- | ------ | ------------- | ---------------- |\n| \"kimi-k2-myšlení\" | `jestli/` |**Neomezeno**| Žádný nahlášený strop |\n| `qwen3-coder-plus` | `jestli/` |**Neomezeno**| Žádný nahlášený strop |\n| `deepseek-r1` | `jestli/` |**Neomezeno**| Žádný nahlášený strop |\n| `minimax-m2.1` | `jestli/` |**Neomezeno**| Žádný nahlášený strop |\n| \"kimi-k2\" | `jestli/` |**Neomezeno**| Žádný nahlášený strop |\n\n> Doporučený způsob připojení:**Personal Access Token + `qodercli`**. OAuth prohlížeče je\n> experimentální a ve výchozím nastavení zakázáno, pokud nejsou nakonfigurovány proměnné prostředí `QODER_OAUTH_*`.### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Předpona | Limit | Limit sazby |\n| -------------------- | ------ | ------------- | -------------------- |\n| `qwen3-coder-plus` | `qw/` |**Neomezeno**| Žádný nahlášený strop |\n| `qwen3-coder-flash` | `qw/` |**Neomezeno**| Žádný nahlášený strop |\n| `qwen3-coder-next` | `qw/` |**Neomezeno**| Žádný nahlášený strop |\n| \"model vidění\" | `qw/` |**Neomezeno**| Multimodální (obrázky) |### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Předpona | Limit | Limit sazby |\n| ------------------------- | ------ | ---------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` |**180 tis./měsíc**+ 1 tis./den | Měsíční reset |\n| `gemini-2.5-pro` | `gc/` | 180 tis./měsíc (sdílený bazén) | Vysoká kvalita |### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Úroveň | Denní limit | Limit sazby | Poznámky |\n| ---------- | ------------ | ----------- | ------------------------------------------------------- |\n| Zdarma (Dev) | Žádný token cap |**~40 RPM**| 70+ modelů; přechod na limity čisté sazby v polovině roku 2025 |\n\nPopular free models: `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 (Free API Key — inference.cerebras.ai)\n\n| Úroveň | Denní limit | Limit sazby | Poznámky |\n| ---- | ------------------ | ----------------- | -------------------------------------------- |\n| Zdarma |**1 mil. tokenů/den**| 60 000 TPM / 30 RPM | Světově nejrychlejší odvození LLM; resetuje denně |\n\nDostupné zdarma: `lama-3.3-70b`, `lama-3.1-8b`, `deepseek-r1-distill-lama-70b`### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Úroveň | Denní limit | Limit sazby | Poznámky |\n| ---- | ------------- | ----------------- | ------------------------------------------ |\n| Zdarma |**14,4K RPD**| 30 ot./min na model | Žádná kreditní karta; 429 na limit, neúčtuje se |\n\nDostupné zdarma: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Předpona | Denní kvóta zdarma | Poznámky |\n| ------------------------------ | ------ | ------------------ | ------------------------ |\n| \"LongCat-Flash-Lite\" | `lc/` |**50 milionů tokenů**💥 | Největší bezplatná kvóta všech dob |\n| \"LongCat-Flash-Chat\" | `lc/` | 500 000 tokenů | Víceotáčkový chat |\n| \"LongCat-Flash-Thinking\" | `lc/` | 500 000 tokenů | Zdůvodnění / CoT |\n| \"LongCat-Flash-Thinking-2601\" | `lc/` | 500 000 tokenů | Verze z ledna 2026 |\n| \"LongCat-Flash-Omni-2603\" | `lc/` | 500 000 tokenů | Multimodální |\n\n> 100 % zdarma ve veřejné beta verzi. Zaregistrujte se na [longcat.chat](https://longcat.chat) pomocí e-mailu nebo telefonu. Resetuje se denně v 00:00 UTC.### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Předpona | Limit sazby | Poskytovatel za |\n| ---------- | ------ | ---------- | ------------------- |\n| \"openai\" | `pol/` | 1 požadavek/15s | GPT-5 |\n| \"claude\" | `pol/` | 1 požadavek/15s | Antropický Claude |\n| \"blíženci\" | `pol/` | 1 požadavek/15s | Google Gemini |\n| \"hluboké vyhledávání\" | `pol/` | 1 požadavek/15s | DeepSeek V3 |\n| \"lama\" | `pol/` | 1 požadavek/15s | Meta Llama 4 Scout |\n| \"mistrál\" | `pol/` | 1 požadavek/15s | Mistral AI |\n\n> ✨**Nulové tření:**Žádná registrace, žádný klíč API. Přidejte poskytovatele Pollinations s prázdným polem klíče a funguje to okamžitě.### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Úroveň | Denní neurony | Ekvivalentní použití | Poznámky |\n| ---- | ------------- | ---------------------------------------- | ------------------------ |\n| Zdarma |**10 000**| ~150 LLM resp / 500s audio / 15K vložení | Global edge, 50+ modelů |\n\nOblíbené bezplatné modely: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (zvuk zdarma!), `@cf/qwen/qwen2.5-coder-`1\n\n> Vyžaduje API Token + ID účtu z [dash.cloudflare.com](https://dash.cloudflare.com). Uložte ID účtu v nastavení poskytovatele.### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Úroveň | Kvóta zdarma | Umístění | Poznámky |\n| ---- | ------------- | ------------ | ------------------------------------ |\n| Zdarma |**1 milion tokenů**| 🇫🇷 Paříž, EU | V rámci limitů není potřeba žádná kreditní karta |\n\nDostupné zdarma: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> V souladu s EU/GDPR. Získejte API klíč na [console.scaleway.com](https://console.scaleway.com).\n\n>**💡 The Ultimate Free Stack (11 poskytovatelů, 0 $ navždy):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku NEOMEZENO\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite – 50 milionů tokenů/den 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — není potřeba žádný klíč\n> Qwen (qw/) → modely qwen3-kodér NEOMEZENÉ\n> Gemini (gemini/) → Gemini 2.5 Flash — 1 500 req/den zdarma\n> Cloudflare AI (cf/) → 50+ modelů — 10 000 neuronů/den\n> Scaleway (scw/) → Qwen3 235B, Llama 70B – 1M bezplatných tokenů (EU)\n> Groq (groq/) → Llama/Gemma – ultrarychlé 14,4 000 požadavků/den\n> NVIDIA NIM (nvidia/) → 70+ otevřených modelů — 40 RPM navždy\n> Cerebras (cerebras/) → Nejrychlejší lama/Qwen na světě – 1 milion toku/den\n> ```## 🎙️ Free Transcription Combo\n\n> Přepis jakéhokoli zvuku/videa za**$0**— Deepgram vede s 200 $ zdarma, AssemblyAI 50 $ nouzové zálohy, Groq Whisper jako neomezené nouzové zálohování.\n\n| Poskytovatel | Kredity zdarma | Nejlepší modelka | Limit sazby |\n| ------------------ | ----------------------- | --------------------------------------------- | ----------------------------- |\n| 🢢**Deepgram**|**200 $ zdarma**(registrace) | `nova-3` — nejlepší přesnost, více než 30 jazyků | Žádný limit RPM na bezplatné kredity |\n| 🔵**SestaveníAI**|**50 $ zdarma**(registrace) | `universal-3-pro` — kapitoly, sentiment, PII | Žádný limit RPM na bezplatné kredity |\n| 🔴**Groq**|**Navždy zdarma**| `whisper-large-v3` — OpenAI Whisper | 30 RPM (rychlost omezená) |\n\n**Doporučená kombinace v `/dashboard/combos`:**```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n````\n\nPoté v `/dashboard/media` → karta**Přepis**: nahrajte jakýkoli zvukový nebo video soubor → vyberte svůj kombinovaný koncový bod → získejte přepis v podporovaných formátech.## 💡 Key Features\n\nOmniRoute v2.0 je postaven jako operační platforma, nikoli pouze jako přenosová proxy.### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Funkce | Co to dělá |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |\n| ⚡**Grok-4 Fast Family** | xAI modely za 0,20 $/0,50 $/M – srovnávací 1143 ms (o 30 % rychlejší než Gemini 2.5 Flash) |\n| 🧠**GLM-5 přes Z.AI** | 128 000 výstupní kontext, 0,5 $/1 milion – nejnovější vlajková loď z rodiny GLM |\n| 🔮**MiniMax M2.5** | Úvahy + agentní úkoly za 0,30 $/1 milion – významný upgrade z M2,1 |\n| 🎯**toolCalling Flag na model** | „ToolCalling: true/false“ pro model v registru – AutoCombo přeskočí modely, které nepodporují nástroje |\n| 🌍**Multilingual Intent Detection** | Klíčová slova PT/ZH/ES/AR v hodnocení AutoCombo – lepší výběr modelu pro neanglický obsah |\n| 📊**Zástupy založené na benchmarku** | Skutečná latence p95 z kombinovaného bodování zdrojů živých požadavků – AutoCombo se učí ze skutečných dat |\n| 🔁**Požádat o deduplikaci** | Okno pro odstranění duplicitního obsahu založené na hašování obsahu – bezpečné pro více agentů, zabraňuje duplicitním poplatkům |\n| 🔌**Strategie připojitelného směrovače** | Rozšiřitelné rozhraní `RouterStrategy` — přidejte vlastní logiku směrování jako zásuvné moduly | ### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP |\n\n| Funkce | Co to dělá |\n| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |\n| 🎮**Modelové hřiště** | Stránka řídicího panelu pro přímé testování jakéhokoli modelu — voliče poskytovatele/modelu/koncového bodu, editor Monaco, streamování, přerušení, načasování |\n| 🔏**CLI Fingerprint Matching** | Uspořádání záhlaví/těla podle poskytovatele tak, aby odpovídalo nativním signaturám CLI – přepněte podle poskytovatele v Nastavení > Zabezpečení.**Vaše IP adresa proxy je zachována** |\n| 🤝**Podpora ACP (Protokol klienta agenta)** | Objevování agentů CLI (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 dalších), proces spawner, koncový bod `/api/acp/agents` |\n| 🤖**Hlavní panel agentů AKT** | Debug › Stránka Agenti — mřížka 14 agentů se stavem instalace, verzí, uživatelským formulářem agenta pro libovolný nástroj CLI. Uživatelé**OpenCode**získají tlačítko „Stáhnout opencode.json“, které automaticky vygeneruje konfiguraci připravenou k použití se všemi dostupnými modely. |\n| 🔧**Směrování vlastního modelu `apiFormat`** | Vlastní modely s `apiFormat: \"responses\"` nyní správně směrují do překladače Responses API |\n| 🏢**Codex Workspace Isolation** | Více pracovních prostorů Codex na e-mail — OAuth správně odděluje připojení podle ID pracovního prostoru |\n| 🔄**Elektronová automatická aktualizace** | Desktopová aplikace kontroluje aktualizace + automatická instalace při restartu | ### 🤖 Agent & Protocol Operations (v2.0) |\n\n| Funkce | Co to dělá |\n| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |\n| 🔧**MCP Server (25 nástrojů)** | Nástroje IDE/agenta prostřednictvím 3 přenosů: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 jader + 3 paměti + 4 nástroje pro dovednosti |\n| 🤝**Server A2A (JSON-RPC + SSE)** | Provádění úlohy agent-agent se synchronizací a streamováním |\n| 🧭**Stránka konsolidovaných koncových bodů** | Stránka správy s kartami s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| 🎚️**Přepínače aktivace/deaktivace služby** | Spínače ON/OFF pro MCP a A2A s trvalým nastavením (výchozí: OFF) |\n| 🛰️**MCP Runtime Heartbeat** | Skutečný stav procesu (pid, doba provozu, doba srdečního tepu, transport, režim rozsahu) |\n| 📋**MCP Audit Trail** | Filtrovatelné protokoly auditu s úspěchem/neúspěchem a přiřazením klíče |\n| 🔐**Vymáhání rozsahu MCP** | 10 podrobných oprávnění k rozsahu pro řízený přístup k nástrojům |\n| 📡**A2A Task Lifecycle Management** | Vypsat/filtrovat úlohy, zkontrolovat události/artefakty, zrušit běžící úlohy |\n| 📋**Zjištění karty agenta** | `/.well-known/agent.json` pro automatické zjišťování klienta |\n| 🧪**Protokol E2E Test Harness** | Skutečný MCP SDK + klient A2A toky v `test:protocols:e2e` |\n| ⚙️**Provozní ovládací prvky** | Kombinace přepínačů, použití profilů odolnosti, resetování jističů z jedné ovládací plochy | ### 🧠 Routing & Intelligence |\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------- |\n| 🎯**Chytrý 4úrovňový záložní zdroj** | Automatická trasa: Předplatné → Klíč API → Levné → Zdarma |\n| 📊**Sledování kvót v reálném čase** | Živý počet tokenů + reset odpočítávání na poskytovatele |\n| 🔄**Formátový překlad** | OpenAI ↔ Claude ↔ Gemini ↔ Odpovědi s převody bezpečnými pro schéma |\n| 👥**Podpora více účtů** | Více účtů na poskytovatele s inteligentním výběrem |\n| 🔄**Automatické obnovení tokenu** | Tokeny OAuth se automaticky obnovují s opakováním |\n| 🎨**Vlastní kombinace** | 9 vyvažovacích strategií + řízení záložního řetězce |\n| 🌐**Wildcard Router** | `poskytovatel/*` dynamické směrování |\n| 🧠**Přemýšlení o kontrolách rozpočtu** | Limity průchozího, automatického, vlastního a adaptivního uvažování |\n| 🔀**Aliasy modelů** | Vestavěný + vlastní model aliasing a bezpečnost migrace |\n| ⚡**Degradace pozadí** | Směrujte úlohy s nízkou prioritou na pozadí na levnější modely |\n| 🧪**Inteligentní směrování s ohledem na úkoly** | Automatický výběr modelu podle typu obsahu (kódování/vize/analýza/souhrn) |\n| 🔄**Pracovní postupy agentů A2A** | Deterministický orchestrátor FSM pro stavové spouštění agentů ve více krocích |\n| 🔀**Adaptivní směrování** | Dynamické přepisování strategie založené na objemu tokenů a složitosti výzvy |\n| 🎲**Rozmanitost poskytovatelů** | Shannon entropie bodování vyvažování auto-kombo rozložení provozu |\n| 💬**System Prompt Injection** | Globální ovládací prvky chování používané konzistentně |\n| 📄**Kompatibilita rozhraní Responses API** | Plná podpora `/v1/responses` pro Codex a pokročilé agentní pracovní postupy | ### 🎵 Multi-Modal APIs |\n\n| Funkce | Co to dělá |\n| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |\n| 🖼️**Generování obrázků** | `/v1/images/generations` s cloudem a místními backendy |\n| 📐**Vložení** | `/v1/embeddings` pro vyhledávání a potrubí RAG |\n| 🎤**Přepis zvuku** | `/v1/audio/transscriptions` — 7 poskytovatelů (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), automatická detekce jazyka, podpora MP4/MP3/WAV |\n| 🔊**Převod textu na řeč** | `/v1/audio/speech` — 10 poskytovatelů (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) se správnými chybovými zprávami |\n| 🎬**Generace videa** | `/v1/videos/generations` (pracovní postupy ComfyUI + SD WebUI) |\n| 🎵**Music Generation** | `/v1/music/generations` (pracovní postupy ComfyUI) |\n| 🛡️**Moderování** | `/v1/moderations` bezpečnostní kontroly |\n| 🔀**Reranking** | `/v1/rerank` pro hodnocení relevance |\n| 🔍**Vyhledávání na webu**🆕 | `/v1/search` — 5 poskytovatelů (Serper, Brave, Perplexity, Exa, Tavily), 6 500+ zdarma/měsíc, automatické přepnutí při selhání, mezipaměť | ### 🛡️ Resilience, Security & Governance |\n\n| Funkce | Co to dělá |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------- |\n| 🔌**Jističe** | Vypnutí/obnovení pro každý model s ovládáním prahu |\n| 🎯**Koncové modely** | Vlastní modely deklarují podporované koncové body + formát API |\n| 🛡️**Stádo proti hromům** | Mutex + semaforové ochrany při opakování/rychlosti událostí |\n| 🧠**Sémantická + mezipaměť podpisů** | Snížení nákladů/latence se dvěma vrstvami mezipaměti |\n| ⚡**Žádost o idempotenci** | Duplicitní ochranné okno |\n| 🔒**TLS Fingerprint Spoofing** | Otisk TLS jako v prohlížeči —**snižuje detekci robotů a nahlašování účtu** |\n| 🔏**CLI Fingerprint Matching** | Odpovídá nativním podpisům požadavku CLI —**snižuje riziko zákazu při zachování proxy IP** |\n| 🌐**Filtrování IP** | Kontrola seznamu povolených/blokovaných pro vystavená nasazení |\n| 📊**Upravitelné limity sazeb** | Konfigurovatelné globální limity/limity na úrovni poskytovatele s perzistencí |\n| 📉**Půvabná degradace** | Záložní funkce vícevrstvé ochrany chránící operace hlavní brány |\n| 📜**Config Audit Trail** | Sledování změn založené na rozdílech zabraňující provoznímu posunu s jednoduchým vrácením zpět |\n| ⏳**Provider Health Sync** | Proaktivní monitorování vypršení platnosti tokenu spouštějící výstrahy před selháním autorizace |\n| 🚪**Automaticky zakázat zakázané účty** | Provozní jistič automaticky zaplombuje trvale zablokované tokenové účty |\n| 🔑**Správa klíčů API + rozsah** | Bezpečné vydávání/otočení klíčů a ovládání modelu/poskytovatele |\n| 👁️**Scoped API Key Reveal**🆕 | Přihlaste se k obnově klíčů API prostřednictvím `ALLOW_API_KEY_REVEAL` |\n| 🛡️**Chráněno `/modely`** | Volitelné ověřování a skrytí poskytovatele pro katalog modelů | ### 📊 Observability & Analytics |\n\n| Funkce | Co to dělá |\n| -------------------------------------- | ---------------------------------------------------------------------- | ---------------------------- |\n| 📝**Požadavek + protokolování proxy** | Úplný požadavek/odpověď a protokolování proxy |\n| 📉**Streamované podrobné protokoly**🆕 | Čistě rekonstruuje datové proudy SSE do uživatelského rozhraní |\n| 📋**Sjednocený panel protokolů** | Požadavek, proxy, audit a zobrazení konzoly na jedné stránce |\n| 🔍**Požádejte o telemetrii** | p50/p95/p99 latence a sledování požadavků |\n| 🏥**Health Dashboard** | Doba provozuschopnosti, stavy jističe, uzamčení, statistiky mezipaměti |\n| 💰**Sledování nákladů** | Kontroly rozpočtu a viditelnost cen podle modelu |\n| 📈**Analytické vizualizace** | Statistiky využití modelu/poskytovatele a zobrazení trendů |\n| 🧪**Rámec hodnocení** | Testování zlaté sady s konfigurovatelnými strategiemi shody |\n| 📡**Live Diagnostics**🆕 | Sémantické vynechání mezipaměti pro přesné kombinované živé testování | ### ☁️ Deployment & Platform |\n\n| Funkce | Co to dělá |\n| ----------------------------------------- | ---------------------------------------------------------------------------- | --------------------- |\n| 🌐**Nasadit kdekoli** | Localhost, VPS, Docker, cloudová prostředí |\n| 🚇**Tunel Cloudflare**🆕 | Integrace rychlého tunelu jedním kliknutím z řídicího panelu |\n| 🔑**Filtrování modelu klíče API** | Nativní odpověď /v1/models filtrovaná přes přiřazené kontextové role nosiče |\n| ⚡**Smart Cache Bypass** | Konfigurovatelná heuristika TTL a ovládací prvky nuceného opětovného načtení |\n| 🔄**Zálohování/Obnova** | Export/import a toky obnovy po havárii |\n| 🧙**Průvodce onboardingem** | První spuštění průvodce nastavením |\n| 🔧**CLI Tools Dashboard** | Nastavení jedním kliknutím pro oblíbené kódovací nástroje |\n| 🎮**Modelové hřiště** | Otestujte libovolného poskytovatele/model/koncový bod z řídicího panelu |\n| 🔏**CLI Fingerprint Toggle** | Shoda otisků prstů jednotlivých poskytovatelů v Nastavení > Zabezpečení |\n| 🌐**i18n (30 jazyků)** | Plná podpora řídicího panelu + docs s pokrytím RTL |\n| 🧹**Vymazat všechny modely** | Vymazání seznamu modelů jedním kliknutím v detailech poskytovatele |\n| 👁️**Ovládací prvky postranního panelu**🆕 | Skrýt komponenty a integrace z Nastavení vzhledu |\n| 📋**Šablony vydání** | Standardizované šablony GitHub pro chyby a funkce |\n| 📂**Custom Data Directory** | Přepsání `DATA_DIR` pro umístění úložiště | ### Feature Deep Dive |\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyž kvóta, rychlost nebo stav selžou, OmniRoute automaticky přejde na dalšího kandidáta bez ručního přepínání.#### Protocol management that is visible and operable\n\n- MCP + A2A jsou zjistitelné v uživatelském rozhraní a dokumentech (nejsou skryté)\n- Rozhraní API stavu protokolu zpřístupňují živá provozní data (`/api/mcp/*`, `/api/a2a/*`)\n- Panely obsahují akce pro operace 2. dne (přepínání kombinací, resetování jističe, zrušení úkolu)#### Translator + validation workflow\n\nOblast překladatele zahrnuje:\n\n-**Hřiště**: Vyžádejte si kontroly transformace -**Chat Tester**: kompletní zpáteční cesta na žádost/odpověď -**Testovací stolice**: více případů v jednom běhu -**Live Monitor**: zobrazení dopravy v reálném čase\n\nPlus ověření protokolu se skutečnými klienty pomocí `npm run test:protocols:e2e`.\n\n> 📖**[MCP Server README](open-sse/mcp-server/README.md)**— Reference nástrojů, konfigurace IDE a příklady klientů\n>\n> 📖**[A2A Server README](src/lib/a2a/README.md)**— Dovednosti, metody JSON-RPC, streamování a životní cyklus úloh## 🧪 Evaluations (Evals)\n\nOmniRoute obsahuje vestavěný hodnotící rámec pro testování kvality odezvy LLM oproti zlaté sadě. Přistupte k němu přes**Analytics → Evals**na hlavním panelu.### Built-in Golden Set\n\nPředinstalovaná sada „OmniRoute Golden Set“ obsahuje testovací případy pro:\n\n- Pozdravy, matematika, zeměpis, generování kódu\n- Kompatibilita formátu JSON, překlad, generování markdown\n- Bezpečnostní odmítnutí (škodlivý obsah), počítání, booleovská logika### Evaluation Strategies\n\n| Strategie | Popis | Příklad |\n| ----------------- | ---------------------------------------------------------------------- | ------------------------------- | --- |\n| \"přesný\" | Výstup se musí přesně shodovat | \"4\"\" |\n| \"obsahuje\" | Výstup musí obsahovat podřetězec (nerozlišují se malá a velká písmena) | \"Paříž\" |\n| \"regulární výraz\" | Výstup musí odpovídat vzoru regulárního výrazu | `\"1.*2.*3\"` |\n| \"vlastní\" | Vlastní funkce JS vrací true/false | `(výstup) => výstup.délka > 10` | --- |\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<podrobnosti>\n<summary><b>🧩 Nastavení MCP (Model Context Protocol)</b></summary>\n\nSpusťte přenos MCP v režimu stdio:```bash\nomniroute --mcp\n\n````\n\nDoporučený postup ověření:\n\n1. Připojte svého MCP klienta přes stdio.\n2. Spusťte `omniroute_get_health`.\n3. Spusťte `omniroute_list_combos`.\n4. Otevřete `/dashboard/mcp` pro potvrzení prezenčního signálu, aktivity a auditu.\n\nUžitečná rozhraní API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`</details>\n\n<podrobnosti>\n<summary><b>🤝 Nastavení A2A (Agent2Agent)</b></summary>\n\nObjevte agenta:```bash\ncurl http://localhost:20128/.well-known/agent.json\n````\n\nOdeslat úkol:```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n\n````\n\nSpráva životního cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvozní uživatelské rozhraní:\n\n- `/dashboard/a2a` pro pozorování úkolu/stavu/toku a akce kouře</details>\n\n<podrobnosti>\n<summary><b>🧪 End-to-end validace protokolu</b></summary>\n\nOvěřte oba protokoly se skutečnými klienty:```bash\nnpm run test:protocols:e2e\n````\n\nTím se ověřuje:\n\n- Připojení/seznam/volání klienta MCP SDK\n- A2A objev/odeslat/streamovat/získat/zrušit\n- Křížová kontrola dat v MCP auditu a API pro správu úloh A2A</details>\n\n<podrobnosti>\n<summary><b>💳 Poskytovatelé předplatného</b></summary>### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionály:**Používejte Opus pro složité úkoly, Sonnet pro rychlost. OmniRoute sleduje kvótu na model!### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nKaždý účet Codexu má nyní přepínače zásad v `Dashboard -> Providers`:\n\n- `5h` (ZAP/VYP): vynutit zásadu prahu 5hodinového okna.\n- `Týdně` (ON/OFF): vynutit zásadu týdenního prahu okna.\n- Prahové chování: když povolené okno dosáhne využití >=90 %, daný účet je přeskočen.\n- Rotační chování: OmniRoute automaticky směruje na další způsobilý účet Codex.\n- Resetovat chování: po uplynutí času `resetAt` poskytovatele se účet automaticky znovu stane způsobilým.\n\nScénáře:\n\n- `5h ON` + `Weekly ON`: účet je přeskočen, když kterékoli okno dosáhne prahové hodnoty.\n- `5h VYP` + `Týdně ZAP`: účet může zablokovat pouze používání týdně.\n- `5h ON` + `Týdenní OFF`: účet může zablokovat pouze 5 hodin používání.\n- `resetAt` prošlo: účet automaticky znovu vstoupí do rotace (bez ručního opětovného povolení).### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepší hodnota:**Obrovská bezplatná úroveň! Použijte to před placenými úrovněmi.### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<podrobnosti>\n<summary><b>🔑 Poskytovatelé klíčů API</b></summary>### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Zaregistrujte se: [build.nvidia.com](https://build.nvidia.com)\n2. Získejte bezplatný klíč API (včetně 1000 kreditů pro odvození)\n3. Ovládací panel → Přidat poskytovatele → NVIDIA NIM:\n - Klíč API: `nvapi-your-key`\n\n**Modely:**`nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` a 50+ dalších\n\n**Tip pro profesionály:**API kompatibilní s OpenAI – bezproblémově funguje s překladem formátu OmniRoute!### DeepSeek\n\n1. Zaregistrujte se: [platform.deepseek.com](https://platform.deepseek.com)\n2. Získejte API klíč\n3. Ovládací panel → Přidat poskytovatele → DeepSeek\n\n**Modely:**`deepseek/deepseek-chat`, `deepseek/deepseek-coder`### Groq (Free Tier Available!)\n\n1. Zaregistrujte se: [console.groq.com](https://console.groq.com)\n2. Získejte klíč API (včetně bezplatné úrovně)\n3. Ovládací panel → Přidat poskytovatele → Groq\n\n**Modely:**`groq/lama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Tip pro profesionály:**Ultra rychlé vyvozování – nejlepší pro kódování v reálném čase!### OpenRouter (100+ Models)\n\n1. Zaregistrujte se: [openrouter.ai](https://openrouter.ai)\n2. Získejte API klíč\n3. Ovládací panel → Přidat poskytovatele → OpenRouter\n\n**Modely:**Získejte přístup k více než 100 modelům od všech hlavních poskytovatelů prostřednictvím jediného klíče API.\n\n**Chování řídicího panelu:**Modely OpenRouter jsou spravovány z**Dostupných modelů**. Ruční přidání, import a automatická synchronizace aktualizují stejný seznam.</details>\n\n<podrobnosti>\n<summary><b>💰 Levní poskytovatelé (záložní)</b></summary>### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Zaregistrujte se: [Zhipu AI](https://open.bigmodel.cn/)\n2. Získejte API klíč z Coding Plan\n3. Ovládací panel → Přidat klíč API:\n - Poskytovatel: `glm`\n - Klíč API: `váš klíč`\n\n**Použití:**`glm/glm-4.7`\n\n**Tip pro profesionály:**Kódovací plán nabízí 3× kvótu za 1/7 cenu! Resetovat denně v 10:00.### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Zaregistrujte se: [MiniMax](https://www.minimax.io/)\n2. Získejte API klíč\n3. Ovládací panel → Přidat klíč API\n\n**Použití:**`minimax/MiniMax-M2.1`\n\n**Tip pro profesionály:**Nejlevnější možnost pro dlouhý kontext (1 milion tokenů)!### Kimi K2 ($9/month flat)\n\n1. Přihlaste se k odběru: [Moonshot AI](https://platform.moonshot.ai/)\n2. Získejte API klíč\n3. Ovládací panel → Přidat klíč API\n\n**Použijte:**`kimi/kimi-latest`\n\n**Tip pro profesionály:**Pevná cena 9 $ měsíčně za 10 milionů tokenů = 0,90 $ / 1 milion efektivních nákladů!</details>\n\n<podrobnosti>\n<summary><b>🆓 ZDARMA poskytovatelé (nouzové zálohování)</b></summary>### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<podrobnosti>\n<summary><b>🎨 Vytvořit komba</b></summary>### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<podrobnosti>\n<summary><b>🔧 Integrace CLI</b></summary>### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPoužijte stránku**CLI Tools**na řídicím panelu pro konfiguraci jedním kliknutím nebo upravte `~/.claude/settings.json` ručně.### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Možnost 1 – Hlavní panel (doporučeno):**```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n\n````\n\n**Možnost 2 — Ručně:**Upravit `~/.openclaw/openclaw.json`:```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n````\n\n> **Poznámka:**OpenClaw funguje pouze s místní OmniRoute. Použijte `127.0.0.1` místo `localhost`, abyste se vyhnuli problémům s rozlišením IPv6.### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:**Přidejte OmniRoute jako vlastního poskytovatele:```bash\nopencode\n/connect\n\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n\n````\n\n**Krok 2:**Vytvořte/upravte soubor `opencode.json` v kořenovém adresáři projektu:```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n````\n\n**Krok 3:**Vyberte model v OpenCode:```bash\n/models\n\n# Select any OmniRoute model from the list\n\n````\n\n>**Tip:**Přidejte jakýkoli model dostupný v koncovém bodu vašeho OmniRoute `/v1/models` do sekce `models`. Použijte formát `provider/model-id` z řídicího panelu OmniRoute.</details>\n\n---\n\n## Řešení problémů\n\n<podrobnosti>\n<summary><b>Kliknutím rozbalíte průvodce odstraňováním problémů</b></summary>\n\n**\"Jazykový model neposkytoval zprávy\"**\n\n- Kvóta poskytovatele je vyčerpána → Zkontrolujte sledování kvót na řídicím panelu\n- Řešení: Použijte nouzovou kombinaci nebo přejděte na levnější úroveň\n\n**Omezení sazby**\n\n- Vyčerpaná kvóta předplatného → Záložní režim GLM/MiniMax\n- Přidejte kombinaci: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vypršela**\n\n- Automaticky obnovováno OmniRoute\n- Pokud problémy přetrvávají: Řídicí panel → Poskytovatel → Znovu připojit\n\n**Vysoké náklady**\n\n- Zkontrolujte statistiky využití v Dashboard → Náklady\n- Přepněte primární model na GLM/MiniMax\n- Používejte bezplatnou vrstvu (Gemini CLI, Qoder) pro nekritické úkoly\n\n**Porty řídicího panelu/API jsou chybné**\n\n- `PORT` je kanonický základní port (a port API ve výchozím nastavení)\n- `API_PORT` přepíše pouze posluchače API kompatibilní s OpenAI\n- `DASHBOARD_PORT` přepíše pouze posluchače dashboard/Next.js\n– Nastavte „NEXT_PUBLIC_BASE_URL“ na svůj řídicí panel/veřejnou adresu URL (pro zpětná volání OAuth)\n\n**Chyby synchronizace cloudu**\n\n- Ověřte, že `BASE_URL` odkazuje na vaši spuštěnou instanci\n- Ověřte, že `CLOUD_URL` odkazuje na očekávaný koncový bod cloudu\n- Udržujte hodnoty `NEXT_PUBLIC_*` zarovnané s hodnotami na straně serveru\n\n**První přihlášení nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v `.env`\n- Pokud není nastaveno, záložní heslo je `123456`\n\n**Žádné protokoly požadavků**\n\n- Artefakty požadavku se zapisují do `DATA_DIR/call_logs/` jako jeden soubor JSON na požadavek\n- Povolte zachycení potrubí z řídicího panelu → Protokoly → Protokoly žádostí, pokud potřebujete podrobné užitečné zatížení pro jednotlivé fáze\n- Nastavte `APP_LOG_TO_FILE=true`, pokud chcete také protokoly konzoly aplikace v `logs/application/app.log`\n– Podle potřeby upravte `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES` a `CALL_LOG_MAX_ENTRIES`\n\n**Test připojení ukazuje „Neplatné“ pro poskytovatele kompatibilní s OpenAI**\n\n- Mnoho poskytovatelů nevystavuje koncový bod `/models`\n- OmniRoute v1.0.6+ zahrnuje nouzové ověření prostřednictvím dokončení chatu\n- Zajistěte, aby základní adresa URL obsahovala příponu `/v1`### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n>**⚠️ Důležité pro uživatele provozující OmniRoute na VPS, Dockeru nebo jakémkoli vzdáleném serveru**#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nPoskytovatelé**Antigravity**a**Gemini CLI**používají**Google OAuth 2.0**. Google vyžaduje, aby parametr `redirect_uri` v toku OAuth přesně odpovídal jednomu z předem registrovaných URI v Google Cloud Console aplikace.\n\nPřihlašovací údaje OAuth dodávané v OmniRoute jsou registrovány**pouze pro `localhost`**. Když přistupujete k OmniRoute na vzdáleném serveru (např. `https://omniroute.myserver.com`), Google odmítne ověření pomocí:```\nError 400: redirect_uri_mismatch\n````\n\n#### Solution: Configure your own OAuth credentials\n\nVe službě Google Cloud Console musíte vytvořit**OAuth 2.0 Client ID**s identifikátorem URI vašeho serveru.#### Step-by-step\n\n**1. Otevřít Google Cloud Console**\n\nPřejděte na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvořit nové ID klienta OAuth 2.0**\n\n– Klikněte na**\"+ Vytvořit přihlašovací údaje\"**→**\"ID klienta OAuth\"**\n\n- Typ aplikace:**\"Webová aplikace\"**\n- Název: cokoliv se vám líbí (např. `OmniRoute Remote`)\n\n**3. Přidat identifikátory URI autorizovaného přesměrování**\n\nDo pole**\"URI autorizovaného přesměrování\"**přidejte:```\nhttps://your-server.com/callback\n\n````\n\n> Nahraďte `vas-server.com` doménou nebo IP svého serveru (v případě potřeby uveďte port, např. `http://45.33.32.156:20128/callback`).\n\n**4. Uložte a zkopírujte přihlašovací údaje**\n\nPo vytvoření Google zobrazí**Client ID**a**Client Secret**.\n\n**5. Nastavit proměnné prostředí**\n\nVe vašem `.env` (nebo proměnných prostředí Docker):```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n````\n\n**6. Restartujte OmniRoute**```bash\n\n# npm:\n\nnpm run dev\n\n# Docker:\n\ndocker restart omniroute\n\n````\n\n**7. Zkuste se připojit znovu**\n\nOvládací panel → Poskytovatelé → Antigravitace (nebo Gemini CLI) → OAuth\n\nGoogle se nyní správně přesměruje na `https://vas-server.com/callback`.---\n\n#### Temporary workaround (without custom credentials)\n\nPokud si nyní nechcete nastavovat vlastní přihlašovací údaje, můžete stále použít**ruční postup URL**:\n\n1. OmniRoute otevře autorizační URL Google\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (který selže na vzdáleném serveru)\n3.**Zkopírujte celou adresu URL**z adresního řádku prohlížeče (i když se stránka nenačte)\n4. Vložte tuto adresu URL do pole zobrazeného v modálu připojení OmniRoute\n5. Klikněte na**\"Připojit\"**\n\n> Funguje to, protože autorizační kód v adrese URL je platný bez ohledu na to, zda se stránka přesměrování načetla.---\n\n<podrobnosti>\n<summary><b>🇧🇷 Versão em Português</b></summary>#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOsvedčuje**Antigravity**a**Gemini CLI**používáme**Google OAuth 2.0**pro autenticitu. O Google exige que a `redirect_uri` usada no fluxo OAuth seja**exatamente**uma das URIs pré-cadastradas no Google Cloud Console to use.\n\nJako credenciais OAuth embutidas no OmniRoute estão cadastradas**apenas para `localhost`**. Quando você acessa o OmniRoute um um servidor remote (ex: `https://omniroute.meuservidor.com`), nebo Google rejeita a autenticação com:```\nError 400: redirect_uri_mismatch\n````\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um**OAuth 2.0 Client ID**no Google Cloud Console com a URI do seu server.#### Passo a passo\n\n**1. Přístup ke službě Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Klikněte na**\"+ Vytvořit přihlašovací údaje\"**→**\"ID klienta OAuth\"**\n- Tipo de aplicativo:**\"Webová aplikace\"**\n- Nome: escolha qualquer nome (např.: `OmniRoute Remote`)\n\n**3. Adicione jako Authorized Redirect URI**\n\nŽádné pole**\"URI autorizovaného přesměrování\"**, adicione:```\nhttps://seu-servidor.com/callback\n\n````\n\n> Substitua `seu-servidor.com` pelo domínio nebo IP do seu servidor (včetně portu se necessário, např.: `http://45.33.32.156:20128/callback`).\n\n**4. Uložit a zkopírovat jako credenciais**\n\nApós criar, o Google mostrará o**Client ID**e o**Client Secret**.\n\n**5. Konfigurovat jako variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n````\n\n**6. Reinicie nebo OmniRoute**```bash\n\n# Se usando npm:\n\nnpm run dev\n\n# Se usando Docker:\n\ndocker restart omniroute\n\n````\n\n**7. Tente conectar novamente**\n\nDashboard → Poskytovatelé → Antigravitace (nebo Gemini CLI) → OAuth\n\nAgora nebo Google redirecionamente corretamente para `https://seu-servidor.com/callback` a autenticação funcionará.---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nZjistěte, jaké jsou údaje o vaší kreditní kartě, a je možné, že použijete fluxo**příručku URL**:\n\n1. O OmniRoute abrirá a URL autorização Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3.**Zkopírujte úplnou adresu URL**da barra de endereço do seu browser (mesmo que a pagina não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Klikněte na**\"Připojit\"**\n\n> Toto řešení funguje pomocí autorizačního kódu na URL a nezávislého přesměrování.</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<podrobnosti>\n<summary><b>Kliknutím rozbalíte podrobnosti o technologickém zásobníku</b></summary>\n\n-**Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ není**podporován**– nativní binární soubory `better-sqlite3` jsou nekompatibilní)\n-**Jazyk**: TypeScript 5.9 —**100% TypeScript**napříč `src/` a `open-sse/` (nula `any` v základních modulech od verze 2.0)\n-**Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n-**Databáze**: LowDB (JSON) + SQLite (stav domény + protokoly proxy + audit MCP + rozhodnutí o směrování)\n-**Schémata**: Zod (ověření I/O nástroje MCP, smlouvy API)\n-**Protokoly**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n-**Streamování**: Server-Sent Events (SSE)\n-**Auth**: OAuth 2.0 (PKCE) + JWT + API klíče + MCP Scoped Authorization\n-**Testování**: Testovací program Node.js + Vitest (více než 900 testů včetně jednotky, integrace, E2E)\n-**CI/CD**: Akce GitHub (automatické publikování npm + Docker Hub při vydání)\n-**Web**: [omniroute.online](https://omniroute.online)\n-**Balík**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n-**Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n-**Odolnost**: Jistič, exponenciální ústup, stádo proti hromům, TLS spoofing, auto-kombo samoléčení</details>\n\n---\n\n## Dokumentace\n\n| Dokument | Popis |\n| ---------------------------------------------- | ---------------------------------------------------- |\n| [Uživatelská příručka](docs/USER_GUIDE.md) | Poskytovatelé, komba, integrace CLI, nasazení |\n| [Reference API](docs/API_REFERENCE.md) | Všechny koncové body s příklady |\n| [Server MCP](open-sse/mcp-server/README.md) | 16 MCP nástroje, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamování, správa úloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorové bodování, balíčky režimů, samoléčení |\n| [Odstraňování problémů](docs/TROUBLESHOOTING.md) | Běžné problémy a řešení |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura systému a vnitřní části |\n| [Přispívá](CONTRIBUTING.md) | Vývojové nastavení a pokyny |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpečnostní zásady](SECURITY.md) | Hlášení zranitelnosti a bezpečnostní postupy |\n| [Deployment VM](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletní průvodce: Nastavení VM + nginx + Cloudflare |\n| [Galerie funkcí](docs/FEATURES.md) | Vizuální prohlídka řídicího panelu se snímky obrazovky |\n| [Kontrolní seznam vydání](docs/RELEASE_CHECKLIST.md) | Kroky ověření před vydáním |---\n\n## 🗺️ Roadmap\n\nOmniRoute má naplánováno**210+ funkcí**v několika fázích vývoje. Zde jsou klíčové oblasti:\n\n| Kategorie | Plánované funkce | Hlavní body |\n| ------------------------------ | ----------------- | -------------------------------------------------------------------------------------- |\n| 🧠**Směrování a inteligence**| 25+ | Směrování s nejnižší latencí, směrování založené na značkách, předběžná kontrola kvót, výběr účtu P2C |\n| 🔒**Zabezpečení a dodržování předpisů**| 20+ | Zpevnění SSRF, maskování pověření, rychlostní limit na koncový bod, stanovení rozsahu klíče managementu |\n| 📊**Pozorovatelnost**| 15+ | Integrace OpenTelemetry, sledování kvót v reálném čase, sledování nákladů na model |\n| 🔄**Integrace poskytovatelů**| 20+ | Registr dynamického modelu, cooldowny poskytovatelů, kodex pro více účtů, analýza kvót Copilota |\n| ⚡**Výkon**| 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐**Ekosystém**| 10+ | WebSocket API, konfigurace hot-reload, distribuované úložiště konfigurace, komerční režim |### 🔜 Coming Soon\n\n- 🔗**Integrace OpenCode**– Podpora nativního poskytovatele pro IDE kódování OpenCode AI\n- 🔗**Integrace TRAE**— Plná podpora pro vývojový rámec TRAE AI\n- 📦**Batch API**— Asynchronní dávkové zpracování pro hromadné požadavky\n- 🎯**Směrování založené na značkách**– Směrování požadavků na základě vlastních značek a metadat\n- 💰**Strategie nejnižších nákladů**— Automaticky vyberte nejlevnějšího dostupného poskytovatele\n\n> 📝 Úplné specifikace funkcí dostupné v [`docs/new-features/`](docs/new-features/) (217 podrobných specifikací)---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Rozdělte úložiště\n2. Vytvořte si větev funkcí (`git checkout -b feature/amazing-feature`)\n3. Potvrďte změny (`git commit -m 'Přidat úžasnou funkci'`)\n4. Push do větve (`git Push origin feature/amazing-feature`)\n5. Otevřete žádost o stažení\n\nPodrobné pokyny najdete na [CONTRIBUTING.md](CONTRIBUTING.md).### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n````\n\n---\n\n## 📊 Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## 🙏 Acknowledgments\n\nZvláštní poděkování patří**[9router](https://github.com/decolua/9router)**od**[decolua](https://github.com/decolua)**— původnímu projektu, který inspiroval tento fork. OmniRoute staví na tomto neuvěřitelném základu s dalšími funkcemi, multimodálními API a úplným přepsáním TypeScriptu.\n\nZvláštní poděkování patří**[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)**– původní implementaci Go, která inspirovala tento port JavaScriptu.---\n\n## Licence\n\nLicence MIT – podrobnosti viz [LICENCE](LICENCE).---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "bd281e5753a872fcae52091f909734e96710f61e": {"t": 1785764452.4125838, "n": 106636, "h": "403ccd17ab684fa1", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random)\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** — Progressive retry delays\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 60+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** — Persistent logs that survive server restarts\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** — App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport LOG_TO_FILE=\"${LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v2.0 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 9 balancing strategies + fallback chain control |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ---------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 16 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "19f46eb81743cf9992edc6ff7af268a1da79ffe6": {"t": 1785764454.1418045, "n": 104159, "h": "c6ec9d472b2e7da4", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇹🇷 [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![npm downloads](https://img.shields.io/npm/dm/omniroute?color=cb3837&logo=npm&label=npm%20downloads)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n[![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?logo=docker&color=2496ED&label=docker%20pulls)](https://hub.docker.com/r/diegosouzapw/omniroute)\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random)\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** — Progressive retry delays\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 60+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** — Persistent logs that survive server restarts\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** — App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport LOG_TO_FILE=\"${LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v2.0 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 9 balancing strategies + fallback chain control |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ---------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 16 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "bfeb1693d691d7e3e60da1fc1c81b3ccf113c42f": {"t": 1785764455.7594714, "n": 104221, "h": "a9584470182d688c", "c": "# 🚀 OmniRoute — The Free AI Gateway (Čeština)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇨🇿 [cs](../cs/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![npm downloads](https://img.shields.io/npm/dm/omniroute?color=cb3837&logo=npm&label=npm%20downloads)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n[![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?logo=docker&color=2496ED&label=docker%20pulls)](https://hub.docker.com/r/diegosouzapw/omniroute)\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## Breaking Change: Unified Logging Upgrade\n\n> [!WARNING]\n> **This release changes both the on-disk request log layout and the logging environment variables.**\n>\n> If you are upgrading an existing instance:\n>\n> - Request logs now live in `DATA_DIR/call_logs/YYYY-MM-DD/` as **one JSON artifact per request**.\n> - The old `DATA_DIR/logs/` session folders and `DATA_DIR/log.txt` summary file are removed.\n> - On the first startup after upgrading, OmniRoute creates a safety backup at `DATA_DIR/log_archives/*.zip` before removing the deprecated request log layout.\n> - Legacy logging env vars such as `LOG_TO_FILE`, `LOG_FILE_PATH`, `LOG_MAX_FILE_SIZE`, `LOG_RETENTION_DAYS`, `LOG_LEVEL`, `LOG_FORMAT`, `ENABLE_REQUEST_LOGS`, `CALL_LOGS_MAX`, `CALL_LOG_PAYLOAD_MODE`, and `PROXY_LOG_MAX_ENTRIES` are no longer supported.\n> - Use the new env model instead:\n> - `APP_LOG_TO_FILE`\n> - `APP_LOG_FILE_PATH`\n> - `APP_LOG_MAX_FILE_SIZE`\n> - `APP_LOG_RETENTION_DAYS`\n> - `APP_LOG_MAX_FILES`\n> - `APP_LOG_LEVEL`\n> - `APP_LOG_FORMAT`\n> - `CALL_LOG_RETENTION_DAYS`\n> - `CALL_LOG_MAX_ENTRIES`\n>\n> For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md).\n\n---\n\n## 🆕 What's New\n\n> **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.\n\n| Area | Change |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |\n| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streaming responses (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |\n| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |\n| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |\n| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |\n| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |\n| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |\n| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |\n| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\\...` automatically |\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/google-gemini/gemini-cli\">\n <img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"/><br/>\n <b>Gemini CLI</b>\n </a><br/>\n <sub>⭐ 94.7K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.png\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly)\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random)\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** — Progressive retry delays\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 60+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** — Persistent logs that survive server restarts\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** — App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |\n| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlý start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport LOG_TO_FILE=\"${LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free OAuth — No Credit Card)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v2.0 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 9 balancing strategies + fallback chain control |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Řešení problémů\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n<details>\n<summary><b>🇧🇷 Versão em Português</b></summary>\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas 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:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> 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`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n</details>\n\n---\n\n</details>\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ---------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 16 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "28123355b43a7d77c584d4655aa6f21ad05d1240": {"t": 1785764457.3647902, "n": 92692, "h": "09f5dc6c4ff08788", "c": "# 🚀 OmniRoute — Bezplatná brána umělé inteligence\n\n### Nikdy nepřestávejte s kódováním. Chytré směrování k **BEZPLATNÝM a levným modelům AI** s automatickým přepínáním mezi záložními systémy.\n\n_Váš univerzální API proxy – jeden endpoint, více než 44 poskytovatelů, nulové výpadky. Nyní s orchestrací agentů **MCP a A2A** ._\n\n**Dokončení chatu • Vkládání • Generování obrázků • Video • Hudba • Audio • Změna pořadí • **Vyhledávání na webu** • MCP server • A2A protokol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n</div>\n<p data-md-type=\"paragraph\"><a href=\"https://www.npmjs.com/package/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/npm/v/omniroute?color=cb3837&amp;logo=npm\" alt=\"verze npm\" data-md-type=\"image\"><a href=\"https://hub.docker.com/r/diegosouzapw/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&amp;logo=docker&amp;color=2496ED\" alt=\"Docker Hub\" data-md-type=\"image\"><a href=\"https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/github/license/diegosouzapw/OmniRoute\" alt=\"Licence\" data-md-type=\"image\"><a href=\"https://omniroute.online\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&amp;logoColor=white\" alt=\"Webové stránky\" data-md-type=\"image\"><a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&amp;logoColor=white\" alt=\"WhatsApp\" data-md-type=\"image\"></p>\n<p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\" data-md-type=\"link\">🌐 Webové stránky</a> • <a href=\"#-quick-start\" data-md-type=\"link\">🚀 Rychlý start</a> • <a href=\"#-key-features\" data-md-type=\"link\">💡 Funkce</a> • <a href=\"#-documentation\" data-md-type=\"link\">📖 Dokumentace</a> • <a href=\"#-pricing-at-a-glance\" data-md-type=\"link\">💰 Ceník</a> • <a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\">💬 WhatsApp</a></p>\n<div data-md-type=\"block_html\"></div>\n\n🌐 **Dostupné v:** 🇺🇸 [Angličtina](README.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [maďarština](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonésie](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nizozemsko](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)\n\n---\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| ------------------------------- | --------------------------------------------------------------------------------- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n## 🖼️ Hlavní ovládací panel\n\n<div align=\"center\"> <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"Řídicí panel OmniRoute\" width=\"800\"> </div>\n\n---\n\n## 📸 Náhled řídicího panelu\n\n<details>\n<summary><b>Kliknutím zobrazíte snímky obrazovky z řídicího panelu</b></summary>\n</details>\n\n| Strana | Snímek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelé** | ![Poskytovatelé](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdraví** | ![Zdraví](docs/screenshots/04-health.png) |\n| **Překladatel** | ![Překladatel](docs/screenshots/05-translator.png) |\n| **Nastavení** | ![Nastavení](docs/screenshots/06-settings.png) |\n| **Nástroje CLI** | ![Nástroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly používání** | ![Používání](docs/screenshots/08-usage.png) |\n| **Koncové body** | ![Koncové body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### 🤖 Bezplatný poskytovatel umělé inteligence pro vaše oblíbené programátory\n\n_Připojte libovolný nástroj IDE nebo CLI s umělou inteligencí přes OmniRoute — bezplatnou API bránu pro neomezené kódování._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openclaw/openclaw\"><img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"><br><b>OpenClaw</b></a><br> <sub>⭐ 205 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/HKUDS/nanobot\"><img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"><br><b>NanoBot</b></a><br> <sub>⭐ 20,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/sipeed/picoclaw\"><img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"><br><b>PicoClaw</b></a><br> <sub>⭐ 14,6 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/zeroclaw-labs/zeroclaw\"><img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"><br><b>ZeroClaw</b></a><br> <sub>⭐ 9,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/nearai/ironclaw\"><img src=\"./public/providers/ironclaw.png\" alt=\"Železný dráp\" width=\"48\"><br><b>Železný dráp</b></a><br> <sub>⭐ 2,1 tisíce</sub> </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anomalyco/opencode\"><img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"><br><b>OpenCode</b></a><br> <sub>⭐ 106 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openai/codex\"><img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"><br><b>Codex CLI</b></a><br> <sub>⭐ 60,8 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anthropics/claude-code\"><img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"><br><b>Claude Code</b></a><br> <sub>⭐ 67,3 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/google-gemini/gemini-cli\"><img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"><br> <b>Gemini CLI</b></a><br> <sub>⭐ 94,7 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/Kilo-Org/kilocode\"><img src=\"./public/providers/kilocode.png\" alt=\"Kilo kód\" width=\"48\"><br><b>Kilo kód</b></a><br> <sub>⭐ 15,5 tisíc</sub> </td>\n </tr>\n </table>\n\n<sub>📡 Všichni agenti se připojují přes <code>http://localhost:20128/v1</code> nebo <code>http://cloud.omniroute.online/v1</code> — jedna konfigurace, neomezené modely a kvóty</sub>\n\n---\n\n## 🤔 Proč OmniRoute?\n\n**Přestaňte plýtvat penězi a narážet na limity:**\n\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Kvóta předplatného vyprší každý měsíc\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Limity rychlosti vám zabrání v kódování\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Drahá API (20–50 USD/měsíc na poskytovatele)\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Ruční přepínání mezi poskytovateli\n\n**OmniRoute to řeší:**\n\n- ✅ **Maximalizujte předplatné** – Sledujte kvótu, využijte každou částku před resetováním\n- ✅ **Automatické záložní** – Předplatné → API klíč → Levné → Zdarma, žádné výpadky\n- ✅ **Více účtů** – Round-robin mezi účty u jednotlivých poskytovatelů\n- ✅ **Univerzální** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakýmkoli nástrojem CLI\n\n---\n\n## 📧 Podpora\n\n> 💬 **Přidejte se k naší komunitě!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získejte pomoc, sdílejte tipy a buďte v obraze.\n\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problémy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitní skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Přispívání** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevřete žádost o příspěvek nebo si vyberte `good first issue`\n- **Původní projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### 🐛 Hlásíte chybu?\n\nPři otevírání problému spusťte příkaz system-info a přiložte vygenerovaný soubor:\n\n```bash\nnpm run system-info\n```\n\nTím se vygeneruje soubor `system-info.txt` s verzí Node.js, verzí OmniRoute, podrobnostmi o operačním systému, nainstalovanými nástroji CLI (qoder, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systémovými balíčky – vše, co potřebujeme k rychlé reprodukci vašeho problému. Soubor přiložte přímo k vašemu problému na GitHubu.\n\n---\n\n## 🔄 Jak to funguje\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 Co řeší OmniRoute — 30 skutečných problémů a případů použití\n\n> **Každý vývojář používající nástroje umělé inteligence se s těmito problémy setkává denně.** OmniRoute byl vytvořen tak, aby je všechny vyřešil – od překročení nákladů po regionální bloky, od nefunkčních toků OAuth až po operace s protokoly a sledovatelnost v podniku.\n\n<details>\n<summary><b>💸 1. „Platím si drahé předplatné, ale stále mě ruší limity“</b></summary>\n</details>\n\nVývojáři platí za Claude Pro, Codex Pro nebo GitHub Copilot 20–200 dolarů měsíčně. I při platbě má kvóta strop – 5 hodin používání, týdenní limity nebo limity rychlosti za minutu. Uprostřed kódovací relace poskytovatel přestane reagovat a vývojář ztrácí plynulost a produktivitu.\n\n**Jak to OmniRoute řeší:**\n\n- **Inteligentní čtyřúrovňová záložní služba** – Pokud dojde kvóta předplatného, ​​automaticky se přesměruje na API klíč → Levné → Zdarma bez manuálního zásahu\n- **Sledování kvót v reálném čase** – Zobrazuje spotřebu tokenů v reálném čase s odpočítáváním resetování (5 hodin, denně, týdně)\n- **Podpora více účtů** – Více účtů u jednoho poskytovatele s automatickým přepínáním – když jeden dojde, přepne se na další\n- **Vlastní kombinace** — Přizpůsobitelné záložní řetězce se 6 strategiemi vyvažování (fill-first, round robin, P2C, náhodné, nejméně používané, nákladově optimalizované)\n- **Codex Business Quotas** — Sledování kvót pracovního prostoru firmy/týmu přímo v dashboardu\n\n<details>\n<summary><b>🔌 2. „Potřebuji použít více poskytovatelů, ale každý má jiné API“</b></summary>\n</details>\n\nOpenAI používá jeden formát, Claude (Anthropic) jiný a Gemini ještě třetí. Pokud chce vývojář testovat modely od různých poskytovatelů nebo mezi nimi přecházet, musí překonfigurovat SDK, změnit koncové body a vypořádat se s nekompatibilními formáty. Vlastní poskytovatelé (FriendLI, NIM) mají nestandardní koncové body modelů.\n\n**Jak to OmniRoute řeší:**\n\n- **Sjednocený koncový bod** — Jeden `http://localhost:20128/v1` slouží jako proxy pro všech 67+ poskytovatelů.\n- **Překlad formátu** — Automatický a transparentní: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Sanitizace odpovědí** — Odstraňuje nestandardní pole ( `x_groq` , `usage_breakdown` , `service_tier` ), která porušují OpenAI SDK v1.83+\n- **Normalizace rolí** — Převádí `developer` → `system` pro poskytovatele bez OpenAI; `system` → `user` pro GLM/ERNIE\n- **Extrakce tagů Think** — Extrahuje bloky `<think>` z modelů, jako je DeepSeek R1, do standardizovaného `reasoning_content`\n- **Strukturovaný výstup pro Gemini** — `json_schema` → automatická konverze `responseMimeType` / `responseSchema`\n- **Výchozí hodnota `stream` je `false`** – Odpovídá specifikaci OpenAI, čímž se zabrání neočekávanému SSE v Python/Rust/Go SDK.\n\n<details>\n<summary><b>🌐 3. „Můj poskytovatel AI blokuje můj region/zemi“</b></summary>\n</details>\n\nPoskytovatelé jako OpenAI/Codex blokují přístup z určitých geografických oblastí. Uživatelé se během připojení OAuth a API dostávají k chybám jako `unsupported_country_region_territory` . To je obzvláště frustrující pro vývojáře z rozvojových zemí.\n\n**Jak to OmniRoute řeší:**\n\n- **3úrovňová konfigurace proxy** – Konfigurovatelná proxy na 3 úrovních: globální (veškerý provoz), pro jednotlivé poskytovatele (pouze jeden poskytovatel) a pro jednotlivé připojení/klíč\n- **Barevně kódované odznaky proxy** – Vizuální indikátory: 🟢 globální proxy, 🟡 proxy poskytovatele, 🔵 proxy připojení, vždy zobrazující IP adresu\n- **Výměna tokenů OAuth prostřednictvím proxy** – tok OAuth také prochází přes proxy, čímž se řeší `unsupported_country_region_territory`\n- **Testy připojení přes proxy** – Testy připojení používají nakonfigurovaný proxy (již žádné přímé obcházení)\n- **Podpora SOCKS5** — Plná podpora proxy SOCKS5 pro odchozí směrování\n- **TLS Fingerprint Spoofing** — Otisk prstu TLS podobný prohlížeči pomocí `wreq-js` pro obcházení detekce botů\n- **🔏 Porovnávání otisků prstů v CLI** — Změní pořadí záhlaví a polí v těle serveru tak, aby odpovídala nativním binárním podpisům v CLI, čímž drasticky snižuje riziko nahlašování účtu. IP adresa proxy je zachována — získáte současně stealth **i** maskování IP adresy.\n\n<details>\n<summary><b>🆓 4. „Chci používat umělou inteligenci pro kódování, ale nemám peníze“</b></summary>\n</details>\n\nNe každý si může dovolit zaplatit 20–200 dolarů měsíčně za předplatné AI. Studenti, vývojáři z rozvíjejících se zemí, amatéři a freelanceři potřebují přístup ke kvalitním modelům za nulovou cenu.\n\n**Jak to OmniRoute řeší:**\n\n- **Vestavění poskytovatelé bezplatné úrovně** — Nativní podpora pro 100% bezplatné poskytovatele: Qoder (5 neomezených modelů přes OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezené modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisíc tokenů/měsíc zdarma)\n- **Ollama Cloud** — Cloudově hostované modely Ollama na `api.ollama.com` s bezplatnou úrovní „Light usage“; použijte prefix `ollamacloud/<model>`\n- **Kombinace pouze zdarma** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/měsíc s nulovými prostoji\n- **NVIDIA NIM Free Access** — ~40 RPM developerský přístup k více než 70 modelům na build.nvidia.com (přechod z kreditů na čisté limity rychlosti)\n- **Strategie optimalizace nákladů** – Strategie směrování, která automaticky vybere nejlevnějšího dostupného poskytovatele\n\n<details>\n<summary><b>🔒 5. „Potřebuji chránit svou bránu umělé inteligence před neoprávněným přístupem“</b></summary>\n</details>\n\nPři zpřístupnění brány umělé inteligence síti (LAN, VPS, Docker) může kdokoli s adresou spotřebovat tokeny/kvótu vývojáře. Bez ochrany jsou API zranitelná vůči zneužití, prompt injection a dalšímu zneužití.\n\n**Jak to OmniRoute řeší:**\n\n- **Správa klíčů API** – generování, rotace a vymezování rozsahu pro každého poskytovatele s vyhrazenou stránkou `/dashboard/api-manager`\n- **Oprávnění na úrovni modelu** – Omezení klíčů API na konkrétní modely ( `openai/*` , zástupné znaky) pomocí přepínače Povolit vše/Omezit\n- **Ochrana koncových bodů API** – Vyžaduje klíč pro `/v1/models` a blokuje konkrétní poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** — Všechny trasy dashboardu chráněné middlewarem `withAuth` + tokeny CSRF\n- **Omezovač rychlosti** — Omezování rychlosti na IP s konfigurovatelnými okny\n- **Filtrování IP adres** — Seznam povolených/blokovaných adres pro řízení přístupu\n- **Ochrana proti vkládání výzev** – Sanitizace proti škodlivým vzorcům výzev\n- **Šifrování AES-256-GCM** – přihlašovací údaje jsou v klidovém stavu šifrovány\n\n<details>\n<summary><b>🛑 6. „Můj poskytovatel selhal a já ztratil/a programovací tok“</b></summary>\n</details>\n\nPoskytovatelé umělé inteligence se mohou stát nestabilními, vracet chyby 5xx nebo dosáhnout dočasných limitů rychlosti. Pokud je vývojář závislý na jediném poskytovateli, je jeho práce přerušena. Bez jističů může opakované pokusy vést k pádu aplikace.\n\n**Jak to OmniRoute řeší:**\n\n- **Jistič pro každý model** – Automatické otevírání/zavírání s konfigurovatelnými prahovými hodnotami a dobou ochlazování (Zavřeno/Otevřeno/Poloviční otevření), rozsah definovaný pro každý model, aby se zabránilo kaskádování bloků\n- **Exponenciální odklad** — Progresivní zpoždění opakování\n- **Anti-Thundering Herd** — ochrana Mutex + semafor proti souběžným bouřím s opakovanými pokusy\n- **Kombinované záložní řetězce** – Pokud primární poskytovatel selže, automaticky se propadne řetězcem bez zásahu.\n- **Kombinovaný jistič** – Automaticky deaktivuje selhávajícího poskytovatele v rámci kombinovaného řetězce\n- **Dashboard stavu** — Monitorování provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti, latence p50/p95/p99\n\n<details>\n<summary><b>🔧 7. „Konfigurace každého nástroje umělé inteligence je zdlouhavá a opakující se“</b></summary>\n</details>\n\nVývojáři používají Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Každý nástroj potřebuje jinou konfiguraci (API endpoint, klíč, model). Překonfigurování při změně poskytovatele nebo modelu je ztráta času.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel nástrojů CLI** — Vyhrazená stránka s nastavením jedním kliknutím pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generátor konfigurace GitHub Copilot** – Generuje `chatLanguageModels.json` pro VS Code s hromadným výběrem modelu\n- **Průvodce zaváděním** – 4krokové nastavení pro začínající uživatele\n- **Jeden koncový bod, všechny modely** – jednou nakonfigurujte `http://localhost:20128/v1` a získejte přístup k více než 44 poskytovatelům\n\n<details>\n<summary><b>🔑 8. „Správa OAuth tokenů od více poskytovatelů je peklo“</b></summary>\n</details>\n\nClaude Code, Codex, Gemini CLI, Copilot – všechny používají OAuth 2.0 s tokeny s vypršením platnosti. Vývojáři se musí neustále znovu autentizovat, řešit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdálených serverech. Obzvláště problematický je OAuth v LAN/VPS.\n\n**Jak to OmniRoute řeší:**\n\n- **Automatická aktualizace tokenů** – Tokeny OAuth se obnovují na pozadí před vypršením platnosti.\n- **Vestavěný OAuth 2.0 (PKCE)** – Automatický tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Více účtů na poskytovatele prostřednictvím extrakce tokenů JWT/ID\n- **OAuth LAN/Remote Fix** — Detekce privátní IP adresy pro `redirect_uri` + manuální režim URL pro vzdálené servery\n- **OAuth Behind Nginx** — Používá `window.location.origin` pro kompatibilitu s reverzní proxy\n- **Průvodce vzdáleným OAuth** – Podrobný návod k přihlašovacím údajům Google Cloud na VPS/Dockeru\n\n<details>\n<summary><b>📊 9. „Nevím, kolik utrácím ani kde“</b></summary>\n</details>\n\nVývojáři používají více placených poskytovatelů, ale nemají jednotný přehled o výdajích. Každý poskytovatel má svůj vlastní fakturační panel, ale neexistuje žádný konsolidovaný přehled. Mohou se hromadit neočekávané náklady.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard pro analýzu nákladů** – Sledování nákladů na token a správa rozpočtu pro každého poskytovatele\n- **Rozpočtové limity na úroveň** – Strop výdajů na úroveň, který spouští automatický záložní režim\n- **Konfigurace cen podle modelu** – Konfigurovatelné ceny podle modelu\n- **Statistiky použití pro každý klíč API** — Počet požadavků a časové razítko posledního použití pro každý klíč\n- **Analytický panel** – Statistické karty, graf využití modelu, tabulka poskytovatelů s mírou úspěšnosti a latencí\n\n<details>\n<summary><b>🐛 10. „Nedokážu diagnostikovat chyby a problémy ve volání umělé inteligence.“</b></summary>\n</details>\n\nKdyž volání selže, vývojář neví, zda se jednalo o limit rychlosti, vypršelý token, špatný formát nebo chybu poskytovatele. Fragmentované protokoly napříč různými terminály. Bez sledovatelnosti je ladění metodou pokus-omyl.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel jednotných protokolů** – 4 karty: Protokoly požadavků, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlížeč protokolů konzole** — Prohlížeč protokolů v reálném čase ve stylu terminálu s barevně kódovanými úrovněmi, automatickým posouváním, vyhledáváním a filtrováním\n- **Protokoly proxy SQLite** – trvalé protokoly, které přežijí restart serveru\n- **Překladačské hřiště** — 4 režimy ladění: Hřiště (překlad formátu), Tester chatu (okružní), Testovací stůl (dávkový), Živý monitor (v reálném čase)\n- **Telemetrie požadavků** — latence p50/p95/p99 + trasování X-Request-Id\n- **Souborové protokolování s rotací** – Konzolový interceptor zachycuje vše do protokolu JSON s rotací na základě velikosti\n- **Zpráva o systémových informacích** — příkaz `npm run system-info` vygeneruje `system-info.txt` s kompletním popisem vašeho prostředí (verze uzlu, verze OmniRoute, operační systém, nástroje CLI, stav Dockeru/PM2). Přiložte jej při hlášení problémů pro okamžité třídění.\n\n<details>\n<summary><b>🏗️ 11. „Nasazení a údržba brány je složitá“</b></summary>\n</details>\n\nInstalace, konfigurace a údržba AI proxy v různých prostředích (lokální, VPS, Docker, cloud) je pracná. Problémy, jako jsou pevně zakódované cesty, `EACCES` u adresářů, konflikty portů a multiplatformní sestavení, přispívají k obtížím.\n\n**Jak to OmniRoute řeší:**\n\n- **npm globální instalace** — `npm install -g omniroute && omniroute` — hotovo\n- **Docker Multi-Platform** — AMD64 + nativní ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** — `base` (bez nástrojů CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopová aplikace Electron** — Nativní aplikace pro Windows/macOS/Linux se systémovou lištou, automatickým spuštěním a offline režimem\n- **Režim rozdělených portů** – API a řídicí panel na samostatných portech pro pokročilé scénáře (reverzní proxy, síťování kontejnerů)\n- **Cloud Sync** – Konfigurace synchronizace mezi zařízeními pomocí Cloudflare Workers\n- **Zálohy databází** — Automatické zálohování, obnovení, export a import všech nastavení\n\n<details>\n<summary><b>🌍 12. „Rozhraní je pouze v angličtině a můj tým nemluví anglicky“</b></summary>\n</details>\n\nTýmy v neanglicky mluvících zemích, zejména v Latinské Americe, Asii a Evropě, se potýkají s rozhraními pouze v angličtině. Jazykové bariéry snižují míru přijetí a zvyšují chyby v konfiguraci.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard i18n — 30 jazyků** — Všech 500+ kláves je přeloženo včetně arabštiny, bulharštiny, dánštiny, němčiny, španělštiny, finštiny, francouzštiny, hebrejštiny, hindštiny, maďarštiny, indonéštiny, italštiny, japonštiny, korejštiny, malajštiny, holandštiny, norštiny, polštiny, portugalštiny (PT/BR), rumunštiny, ruštiny, slovenštiny, švédštiny, thajštiny, ukrajinštiny, vietnamštiny, čínštiny, filipínštiny a angličtiny\n- **Podpora RTL** – Podpora psaní zprava doleva pro arabštinu a hebrejštinu\n- **Vícejazyčné soubory README** — 30 kompletních překladů dokumentace\n- **Výběr jazyka** — Ikona glóbu v záhlaví pro přepínání v reálném čase\n\n<details>\n<summary><b>🔄 13. „Potřebuji víc než jen chat – potřebuji vložené soubory, obrázky, zvuk.“</b></summary>\n</details>\n\nUmělá inteligence není jen dokončování chatu. Vývojáři potřebují generovat obrázky, přepisovat zvuk, vytvářet embeddedy pro RAG, měnit pořadí dokumentů a moderovat obsah. Každé API má jiný koncový bod a formát.\n\n**Jak to OmniRoute řeší:**\n\n- **Vkládání** — `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generování obrázků** — `/v1/images/generations` s 10 poskytovateli a více než 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Převod textu na video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Převod textu na hudbu** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Přepis zvuku** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Převod textu na řeč** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a další stávající poskytovatelé\n- **Moderování** — `/v1/moderations` — Kontroly bezpečnosti obsahu\n- **Změna pořadí** — `/v1/rerank` — Změna pořadí relevance dokumentu\n- **Responses API** — Plná podpora `/v1/responses` pro Codex\n\n<details>\n<summary><b>🧪 14. „Nemám způsob, jak testovat a porovnávat kvalitu napříč modely.“</b></summary>\n</details>\n\nVývojáři chtějí vědět, který model je pro jejich případ použití nejlepší – kód, překlad, uvažování – ale ruční porovnávání je pomalé. Neexistují žádné integrované nástroje pro vyhodnocování.\n\n**Jak to OmniRoute řeší:**\n\n- **Hodnocení LLM** — Testování Golden setu s 10 předinstalovanými případy zahrnujícími pozdravy, matematiku, geografii, generování kódu, dodržování JSON, překlad, markdown, odmítnutí bezpečnostních požadavků\n- **4 strategie shody** — `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovací lavice pro překladatelské hřiště** — Dávkové testování s více vstupy a očekávanými výstupy, porovnání napříč poskytovateli\n- **Tester chatu** — Kompletní okružní cesta s vizuálním vykreslováním odpovědí\n- **Živý monitor** — Stream všech požadavků procházejících proxy serverem v reálném čase\n\n<details>\n<summary><b>📈 15. „Potřebuji škálovat bez ztráty výkonu“</b></summary>\n</details>\n\nS rostoucím objemem požadavků generují stejné otázky bez ukládání do mezipaměti duplicitní náklady. Bez idempotence duplicitní požadavky plýtvají zpracováním. Je nutné dodržovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute řeší:**\n\n- **Sémantická mezipaměť** — Dvouvrstvá mezipaměť (signatura + sémantika) snižuje náklady a latenci\n- **Idempotence požadavku** — 5s deduplikační okno pro identické požadavky\n- **Detekce limitu rychlosti** – sledování otáček za minutu (RPM), minimální mezera a maximální souběžné sledování pro každého poskytovatele\n- **Upravitelné limity rychlosti** — Konfigurovatelné výchozí hodnoty v Nastavení → Odolnost s perzistencí\n- **Mezipaměť pro ověření klíčů API** — třívrstvá mezipaměť pro výkon produkčního prostředí\n- **Dashboard s telemetrií** – latence p50/p95/p99, statistiky mezipaměti, dostupnost\n\n<details>\n<summary><b>🤖 16. „Chci mít chování modelů globálně pod kontrolou“</b></summary>\n</details>\n\nVývojáři, kteří chtějí všechny odpovědi v určitém jazyce, se specifickým tónem nebo chtějí omezit tokeny pro uvažování. Konfigurace této funkce v každém nástroji/požadavku je nepraktická.\n\n**Jak to OmniRoute řeší:**\n\n- **Vložení systémového prompt** – Globální prompt aplikovaný na všechny požadavky\n- **Validace rozpočtu Thinking** — Řízení alokace tokenů na požadavek (průchozí, automatické, vlastní, adaptivní)\n- **6 strategií směrování** – Globální strategie, které určují, jak jsou požadavky distribuovány\n- **Směrovač se zástupnými znaky** — vzory `provider/*` dynamicky směrují k libovolnému poskytovateli\n- **Přepínání povolení/zakázání kombinací** – Přepínání kombinací přímo z řídicího panelu\n- **Přepínání poskytovatele** – Povolení/zakázání všech připojení pro poskytovatele jedním kliknutím\n- **Blokovaní poskytovatelé** – Vyloučení konkrétních poskytovatelů ze seznamu `/v1/models`\n\n<details>\n<summary><b>🧰 17. „Potřebuji nástroje MCP jako prvotřídní produktové funkce.“</b></summary>\n</details>\n\nMnoho bran umělé inteligence odhaluje MCP pouze jako skrytý implementační detail. Týmy potřebují viditelnou a spravovatelnou operační vrstvu.\n\n**Jak to OmniRoute řeší:**\n\n- MCP se zobrazuje v navigaci na řídicím panelu a na kartě protokolu koncového bodu.\n- Vyhrazená stránka pro správu MCP s procesy, nástroji, rozsahy a auditem\n- Vestavěný rychlý start pro `omniroute --mcp` a onboarding klienta\n\n<details>\n<summary><b>🧠 18. „Potřebuji orchestraci A2A se synchronizací a cestami úloh streamu.“</b></summary>\n</details>\n\nPracovní postupy agentů vyžadují jak přímé odpovědi, tak dlouhodobé streamované provádění s kontrolou životního cyklu.\n\n**Jak to OmniRoute řeší:**\n\n- Koncový bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamování SSE s šířením stavu terminálu\n- Rozhraní API životního cyklu úloh pro `tasks/get` a `tasks/cancel`\n\n<details>\n<summary><b>🛰️ 19. „Potřebuji skutečný stav procesu MCP, ne odhadovaný stav.“</b></summary>\n</details>\n\nProvozní týmy potřebují vědět, zda je MCP skutečně aktivní, nejen zda je API dosažitelné.\n\n**Jak to OmniRoute řeší:**\n\n- Soubor běhového heartbeatu s PID, časovými razítky, transportem, počtem nástrojů a režimem rozsahu\n- API stavu MCP kombinující prezenční signál a nedávnou aktivitu\n- Karty stavu uživatelského rozhraní pro zobrazení aktuálnosti procesů/provozuschopnosti/prezenčního signálu\n\n<details>\n<summary><b>📋 20. „Potřebuji auditovatelné provedení nástroje MCP“</b></summary>\n</details>\n\nKdyž nástroje mění konfiguraci nebo spouštějí operační akce, týmy potřebují forenzní sledovatelnost.\n\n**Jak to OmniRoute řeší:**\n\n- Protokolování auditu pro volání nástrojů MCP s podporou SQLite\n- Filtruje podle nástroje, úspěchu/neúspěchu, klíče API a stránkování\n- Tabulka auditu dashboardu + koncové body statistik pro automatizaci\n\n<details>\n<summary><b>🔐 21. „Potřebuji omezená oprávnění MCP pro každou integraci.“</b></summary>\n</details>\n\nRůzní klienti by měli mít přístup ke kategoriím nástrojů s nejnižšími oprávněními.\n\n**Jak to OmniRoute řeší:**\n\n- 9 detailních MCP sond pro kontrolovaný přístup k nástrojům\n- Vynucení rozsahu a viditelnost v uživatelském rozhraní správy MCP\n- Bezpečná výchozí poloha pro provozní nástroje\n\n<details>\n<summary><b>⚙️ 22. „Potřebuji provozní kontroly bez nutnosti přesouvání“</b></summary>\n</details>\n\nTýmy potřebují rychlé změny v běhovém prostředí během incidentů nebo nákladových událostí.\n\n**Jak to OmniRoute řeší:**\n\n- Přepněte aktivaci komba přímo z řídicího panelu MCP\n- Používejte profily odolnosti z předdefinovaných balíčků zásad\n- Resetujte stav jističe ze stejného ovládacího panelu\n\n<details>\n<summary><b>🔄 23. „Potřebuji živý přehled o životním cyklu úkolů A2A a jejich zrušení.“</b></summary>\n</details>\n\nBez přehledu o životním cyklu je obtížné třídit incidenty úkolů.\n\n**Jak to OmniRoute řeší:**\n\n- Výpis/filtrování úkolů podle státu/dovednosti s stránkováním\n- Podrobný přehled metadat úloh, událostí a artefaktů\n- Koncový bod zrušení úlohy a akce uživatelského rozhraní s potvrzením\n\n<details>\n<summary><b>🌊 24. „Potřebuji metriky aktivního streamu pro A2A zátěž“</b></summary>\n</details>\n\nStreamovací pracovní postupy vyžadují provozní přehled o souběžnosti a živých připojeních.\n\n**Jak to OmniRoute řeší:**\n\n- Čítače aktivních streamů integrované do stavu A2A\n- Časové razítko posledního úkolu a počty pro jednotlivé stavy\n- Karty A2A dashboardu pro monitorování provozu v reálném čase\n\n<details>\n<summary><b>🪪 25. „Potřebuji standardní vyhledávání agentů pro klienty“</b></summary>\n</details>\n\nExterní klienti a orchestratoři potřebují pro onboarding strojově čitelná metadata.\n\n**Jak to OmniRoute řeší:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazené v uživatelském rozhraní pro správu\n- API pro stav A2A zahrnuje metadata pro zjišťování pro automatizaci\n\n<details>\n<summary><b>🧭 26. „Potřebuji v uživatelském rozhraní produktu zjistitelnost protokolu.“</b></summary>\n</details>\n\nPokud uživatelé nemohou objevit protokolové povrchy, kvalita přijetí a podpory klesá.\n\n**Jak to OmniRoute řeší:**\n\n- Stránka Konsolidované **koncové body** s kartami pro koncové body Proxy, MCP, A2A a API\n- Přepínání stavu inline služby (Online/Offline) pro MCP a A2A\n- Odkazy z přehledu na vyhrazené karty pro správu\n\n<details>\n<summary><b>🧪 27. „Potřebuji komplexní ověření protokolu se skutečnými klienty.“</b></summary>\n</details>\n\nSimulované testy nestačí k ověření kompatibility protokolu před vydáním.\n\n**Jak to OmniRoute řeší:**\n\n- Sada E2E, která spouští aplikaci a používá skutečný transport klienta MCP SDK.\n- Klientské testy A2A pro toky zjišťování, odesílání, streamování, načítání a zrušení\n- Křížová kontrola tvrzení oproti API pro audit MCP a úkoly A2A\n\n<details>\n<summary><b>📡 28. „Potřebuji jednotnou pozorovatelnost napříč všemi rozhraními“</b></summary>\n</details>\n\nRozdělení pozorovatelnosti podle protokolu vytváří slepá místa a delší MTTR.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocené dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie požadavků napříč vrstvami OpenAI, MCP a A2A\n- Provozní API pro stav a automatizaci\n\n<details>\n<summary><b>💼 29. „Potřebuji jeden runtime pro proxy + nástroje + orchestraci agentů“</b></summary>\n</details>\n\nSpouštění mnoha samostatných služeb zvyšuje provozní náklady a počet poruch.\n\n**Jak to OmniRoute řeší:**\n\n- Proxy, MCP server a A2A server kompatibilní s OpenAI v jednom balíčku\n- Sdílené ověřování, odolnost, úložiště dat a pozorovatelnost\n- Konzistentní model politik napříč všemi interakčními plochami\n\n<details>\n<summary><b>🚀 30. „Potřebuji agentské pracovní postupy bez slepení kódu.“</b></summary>\n</details>\n\nTýmy ztrácejí rychlost při spojování více ad-hoc služeb a skriptů.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocená strategie koncových bodů pro klienty a agenty\n- Vestavěná uživatelská rozhraní pro správu protokolů a cesty pro ověřování kouře\n- Základy připravené pro produkční prostředí (zabezpečení, protokolování, odolnost, zálohování)\n\n### Příklady herních plánů (integrované případy užití)\n\n**Příručka A: Maximalizace placeného předplatného + levné zálohování**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Příručka B: Kódovací stack s nulovými náklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Příručka C: Nonstop záložní řetězec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Příručka D: Operace agentů s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Začněte zdarma — Nulové náklady na konfiguraci\n\n> Nastavte si kódování s umělou inteligencí během několika minut za **0 $/měsíc** . Propojte tyto bezplatné účty a využijte vestavěnou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelé odemčeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Připojení **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 – **neomezeně** |\n| 2 | Připojení k **Qoder** (Google OAuth) | kimi-k2-myšlení, qwen3-coder-plus, deepseek-r1... — **neomezeně** |\n| 3 | Připojení **Qwen** (kód zařízení) | qwen3-coder-plus, qwen3-coder-flash... — **neomezeně** |\n| 4 | Připojení **rozhraní příkazového řádku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180 000 GBP/měsíc zdarma** |\n| 5 | `/dashboard/combos` → Šablona **Free Stack (0 $)** | Automatické zařazení všech bezplatných poskytovatelů do routingu |\n\n**V libovolném IDE/CLI naveďte:** `http://localhost:20128/v1` · Klíč API: `any-string` · Hotovo.\n\n> **Volitelné doplňkové krytí (také zdarma):** Groq API klíč (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelů), Cerebras (1 milion tok/den).\n\n## ⚡ Rychlý start\n\n### 1) Nainstalujte a spusťte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uživatelé pnpm:** Po instalaci spusťte `pnpm approve-builds -g` , abyste povolili nativní skripty pro sestavení vyžadované programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard se otevírá na `http://localhost:20128` a základní URL API je `http://localhost:20128/v1` .\n\n| Příkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuštění serveru ( `PORT=20128` , API a dashboard na stejném portu) |\n| `omniroute --port 3000` | Nastavte kanonický/API port na 3000 |\n| `omniroute --mcp` | Spuštění MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevírat prohlížeč automaticky |\n| `omniroute --help` | Zobrazit nápovědu |\n\nVolitelný režim s rozděleným portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Připojte poskytovatele a vytvořte si klíč API\n\n1. Otevřete Dashboard → `Providers` a připojte alespoň jednoho poskytovatele (klíč OAuth nebo API).\n2. Otevřete Dashboard → `Endpoints` a vytvořte API klíč.\n3. (Volitelné) Otevřete Dashboard → `Combos` a nastavte záložní řetězec.\n\n### 3) Nasměrujte svůj kódovací nástroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilními s OpenAI.\n\n### 4) Povolení a ověření protokolů (v2.0)\n\n**MCP (pro operace řízené nástroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak připojte svého MCP klienta přes `stdio` a otestujte nástroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovní postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ověřte vše od začátku do konce (doporučeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ověřuje skutečné toky klientů MCP a A2A v porovnání se spuštěnou aplikací.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## 🐳 Docker\n\nOmniRoute je k dispozici jako veřejný obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlý běh:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostředí:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Používání Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | Štítek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovější stabilní verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuální verze |\n\n---\n\n## 🖥️ Desktopová aplikace – offline a vždy zapnutá\n\n> 🆕 **NOVINKA!** OmniRoute je nyní k dispozici jako **nativní desktopová aplikace** pro Windows, macOS a Linux.\n\nSpusťte OmniRoute jako samostatnou desktopovou aplikaci – pro lokální modely není potřeba žádný terminál, prohlížeč ani internet. Aplikace založená na platformě Electron obsahuje:\n\n- 🖥️ **Nativní okno** — Vyhrazené okno aplikace s integrací do systémové lišty\n- 🔄 **Automatické spuštění** — Spuštění OmniRoute po přihlášení do systému\n- 🔔 **Nativní oznámení** – Získejte upozornění na vyčerpání kvóty nebo problémy s poskytovateli\n- ⚡ **Instalace jedním kliknutím** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline režim** — Funguje plně offline s přiloženým serverem\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systémový zásobník\n\nPo minimalizaci se OmniRoute nachází v systémové liště a nabízí rychlé akce:\n\n- Otevřít řídicí panel\n- Změnit port serveru\n- Ukončit aplikaci\n\n📖 Úplná dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Přehled cen\n\n| Úroveň | Poskytovatel | Náklady | Obnovení kvóty | Nejlepší pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **💳 PŘEDPLATNÉ** | Claude Code (profesionál) | 20 dolarů měsíčně | 5 hodin + týdně | Již přihlášen/a k odběru |\n| Kodex (Plus/Pro) | 20–200 USD/měsíc | 5 hodin + týdně | Uživatelé OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisíc měsíčně + 1 tisíc denně | Každý! |\n| GitHub Copilot | 10–19 USD/měsíc | Měsíční | Uživatelé GitHubu |\n| **🔑 KLÍČ API** | NVIDIA NIM | **ZDARMA** (vývoj navždy) | ~40 ot./min | 70+ otevřených modelů |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší na světě |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisíc otáček za minutu | Ultrarychlá lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | Žádný | Nejlepší zdůvodnění ceny a kvality |\n| xAI Grok-4 Rychlý | **0,20/0,50 USD za 1 milion** 🆕 | Žádný | Nejrychlejší + volání nástroje, ultranízké |\n| xAI Grok-4 (standardní) | 0,20/1,50 USD za 1 milion 🆕 | Žádný | Vlajková loď Reasoning od xAI |\n| Mistral | Zkušební verze zdarma + placené | Omezená sazba | Evropská umělá inteligence |\n| OpenRouter | Platba za použití | Žádný | Více než 100 modelů agregováno. |\n| **💰 LEVNÉ** | GLM-5 (přes Z.AI) 🆕 | 0,5 USD/1 milion | Denně v 10:00 | Výstup 128 tisíc obrazových bodů, nejnovější vlajková loď |\n| GLM-4.7 | 0,6 USD/1 milion | Denně v 10:00 | Záloha rozpočtu |\n| MiniMax M2.5 🆕 | Vstup 0,3 USD/1 milion | 5hodinové válcování | Úvaha + agentní úkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinové válcování | Nejlevnější varianta |\n| Kimi K2.5 (Moonshot API) 🆕 | Platba za použití | Žádný | Přímý přístup k Moonshot API |\n| Kimi K2 | 9 dolarů měsíčně bez závazků | 10 milionů tokenů/měsíc | Předvídatelné náklady |\n| **🆓 ZDARMA** | Qoder | **0 dolarů** | Neomezený | 5 modelů neomezeně |\n| Qwen | **0 dolarů** | Neomezený | 4 modely neomezeně |\n| Kiro | **0 dolarů** | Neomezený | Claude Sonnet/Haiku (tvorce AWS) |\n\n> 🆕 **Přidány nové modely (březen 2026):** řada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkováno na 1143 ms – o 30 % rychlejší než Gemini 2.5 Flash), GLM-5 přes Z.AI s výstupem 128K, uvažování MiniMax M2.5, aktualizované ceny DeepSeek V3.2, Kimi K2.5 přes Moonshot Direct API.\n\n**💡 Kombinovaný balík za 0 $ — Kompletní bezplatná instalace:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Nulové náklady. Nikdy nepřestávejte s kódováním.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a všechny záložní režimy se provede automaticky – žádné ruční přepínání.\n\n---\n\n---\n\n## 🆓 Bezplatné modely – Co skutečně získáte\n\n> Všechny níže uvedené modely jsou **100% zdarma a nevyžadují žádnou kreditní kartu** . OmniRoute mezi nimi automaticky propojí trasy, když dojde jedna kvóta – zkombinujte je všechny a získejte tak nerozlučnou kombinaci za 0 dolarů.\n\n### 🔵 CLAUDE MODELS (přes Kiro — AWS Builder ID)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-opus-4.6` | `kr/` | **Neomezený** | Nejnovější opus od Kira |\n\n### 🟢 MODELY QODER (Bezplatné OAuth — bez nutnosti platit kreditní kartou)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-plus` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `deepseek-r1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `minimax-m2.1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `kimi-k2` | `if/` | **Neomezený** | Žádný hlášený strop |\n\n### 🟡 MODELY QWEN (Ověření kódu zařízení)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-next` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `vision-model` | `qw/` | **Neomezený** | Multimodální (obrázky) |\n\n### 🟣 Rozhraní GEMINI CLI (Google OAuth)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisíc tok/měsíc** + 1 tisíc/den | Měsíční reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisíc měsíčně (sdílený bazén) | Vysoká kvalita |\n\n### ⚫ NVIDIA NIM (Bezplatný klíč API — build.nvidia.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vývojář) | Žádný limit tokenů | **~40 ot./min** | Více než 70 modelů; přechod na čisté limity sazeb v polovině roku 2025 |\n\nOblíbené bezplatné modely: `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`\n\n### ⚪ CEREBRAS (Bezplatný klíč API — inference.cerebras.ai)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenů/den** | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší inference LLM na světě; denně se resetuje |\n\nDostupné zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Bezplatný API klíč — console.groq.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisíc otáček za minutu** | 30 ot./min na model | Žádná kreditní karta; limit 429, neúčtováno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **💡 Ultimátní bezplatný zásobník:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> → Qoder (5 models, unlimited)\n> → Qwen (4 models, unlimited)\n> → Gemini CLI (180K/mo)\n> → Cerebras (1M tok/day)\n> → Groq (14.4K req/day)\n> → NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a už nikdy nebudete platit za umělou inteligenci.\n\n## 🎙️ Kombinovaná transkripce zdarma\n\n> Přepisujte libovolné audio/video za **0 $** – Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako záložní nástroj, Groq Whisper jako neomezená nouzová záloha.\n\n| Poskytovatel | Bezplatné kredity | Nejlepší model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| 🟢 **Deepgram** | **200 dolarů zdarma** (registrace) | `nova-3` — nejvyšší přesnost, více než 30 jazyků | Žádný limit RPM pro kredity zdarma |\n| 🔵 **AssemblyAI** | **50 dolarů zdarma** (registrace) | `universal-3-pro` — kapitoly, sentiment, osobní údaje | Žádný limit RPM pro kredity zdarma |\n| 🔴 **Groq** | **Navždy zdarma** | `whisper-large-v3` — OpenAI Šepot | 30 ot./min (omezená rychlost) |\n\n**Navrhovaná kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nPak v `/dashboard/media` → záložka **Přepis** : nahrajte libovolný zvukový nebo video soubor → vyberte kombinovaný koncový bod → získejte přepis v podporovaných formátech.\n\n## 💡 Klíčové vlastnosti\n\nOmniRoute v2.0 je navržen jako operační platforma, nikoli pouze jako proxy pro relé.\n\n### 🤖 Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dělá |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **MCP Server (16 nástrojů)** | Nástroje IDE/agent prostřednictvím 3 transportů: stdio, SSE ( `/api/mcp/sse` ), Streamovatelný HTTP ( `/api/mcp/stream` ) |\n| 🤝 **A2A server (JSON-RPC + SSE)** | Spouštění úloh mezi agenty se synchronizací a streamováním |\n| 🧭 **Konsolidovaná stránka koncových bodů** | Stránka pro správu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| 🎚️ **Přepínače pro povolení/zakázání služby** | Přepínače ZAP/VYP pro MCP a A2A s trvalým nastavením (výchozí: VYP) |\n| 🛰️ **Srdeční tep za běhu MCP** | Skutečný stav procesu (pid, doba provozuschopnosti, stáří heartbeatu, transport, režim rozsahu) |\n| 📋 **Auditní záznam MCP** | Filtrovatelné protokoly auditu s hodnocením úspěchu/neúspěchu a klíčovým přiřazením |\n| 🔐 **Vynucování rozsahu MCP** | 9 podrobných oprávnění pro řízený přístup k nástrojům |\n| 📡 **Správa životního cyklu úkolů A2A** | Seznam/filtrování úloh, kontrola událostí/artefaktů, zrušení spuštěných úloh |\n| 📋 **Objevení karty agenta** | `/.well-known/agent.json` pro automatické vyhledávání klientů |\n| 🧪 **Testovací postroj Protocol E2E** | Skutečné MCP SDK + toky klientů A2A v `test:protocols:e2e` |\n| ⚙️ **Provozní kontroly** | Kombinace přepínačů, použití profilů odolnosti, resetování jističů z jednoho ovládacího panelu |\n\n### 🧠 Směrování a inteligence\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| 🎯 **Inteligentní čtyřúrovňový záložní systém** | Automatická trasa: Předplatné → API klíč → Levné → Zdarma |\n| 📊 **Sledování kvót v reálném čase** | Počet tokenů v reálném čase + odpočet resetování pro každého poskytovatele |\n| 🔄 **Překlad formátu** | OpenAI ↔ Claude ↔ Gemini ↔ Odpovědi s konverzemi bezpečnými pro schéma |\n| 👥 **Podpora více účtů** | Více účtů na poskytovatele s inteligentním výběrem |\n| 🔄 **Automatická aktualizace tokenů** | Tokeny OAuth se automaticky obnovují při opakovaném pokusu. |\n| 🎨 **Vlastní kombinace** | 6 vyvažovacích strategií + řízení záložního řetězce |\n| 🌐 **Směrovač se zástupnými znaky** | dynamické směrování `provider/*` |\n| 🧠 **Přemýšlení o rozpočtových kontrolách** | Limity pro průchozí, automatické, vlastní a adaptivní uvažování |\n| 🔀 **Aliasy modelů** | Vestavěné + vlastní aliasování modelů a bezpečnost migrace |\n| ⚡ **Degradace pozadí** | Směrujte úlohy na pozadí s nízkou prioritou na levnější modely |\n| 🧪 **Chytré směrování s ohledem na úkoly** | Automatický výběr modelu podle typu obsahu (kódování/vize/analýza/sumarizace) |\n| 💬 **Vstřikování do systému** | Globální kontroly chování uplatňované konzistentně |\n| 📄 **Kompatibilita API pro odpovědi** | Plná podpora `/v1/responses` pro Codex a pokročilé agentické pracovní postupy |\n\n### 🎵 Multimodální API\n\n| Funkce | Co to dělá |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Generování obrázků** | `/v1/images/generations` s cloudovým a lokálním backendem |\n| 📐 **Vložení** | `/v1/embeddings` pro vyhledávání a RAG pipelines |\n| 🎤 **Přepis zvuku** | `/v1/audio/transcriptions` (Whisper a další poskytovatelé) |\n| 🔊 **Převod textu na řeč** | `/v1/audio/speech` (více enginů/poskytovatelů) |\n| 🎬 **Generování videa** | `/v1/videos/generations` (pracovní postupy ComfyUI + SD WebUI) |\n| 🎵 **Hudební generace** | `/v1/music/generations` (pracovní postupy ComfyUI) |\n| 🛡️ **Moderování** | Bezpečnostní kontroly `/v1/moderations` |\n| 🔀 **Změna pořadí** | `/v1/rerank` pro hodnocení relevance |\n| 🔍 **Vyhledávání na webu** 🆕 | `/v1/search` — 5 poskytovatelů (Serper, Brave, Perplexity, Exa, Tavily), více než 6 500 zdarma/měsíc, automatické přepnutí na záložní systém, mezipaměť |\n\n### 🛡️ Odolnost, bezpečnost a správa věcí veřejných\n\n| Funkce | Co to dělá |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| 🔌 **Jističe** | Vypnutí/obnovení pro každý model s ovládáním prahových hodnot |\n| 🎯 **Modely s ohledem na koncové body** | Vlastní modely deklarují podporované koncové body + formát API |\n| 🛡️ **Stádo proti hromům** | Ochrana mutexu a semaforu při událostech opakování/rychlosti |\n| 🧠 **Sémantická + podpisová mezipaměť** | Snížení nákladů/latence díky dvěma vrstvám mezipaměti |\n| ⚡ **Žádost o idempotenci** | Okno ochrany proti duplikacím |\n| 🔒 **Falšování otisků prstů pomocí TLS** | Otisk TLS podobný prohlížeči – **snižuje detekci botů a nahlašování účtů** |\n| 🔏 **Porovnávání otisků prstů v CLI** | Shoduje se s nativními podpisy požadavků CLI – **snižuje riziko zablokování a zároveň zachovává IP adresu proxy** |\n| 🌐 **Filtrování IP adres** | Ovládání seznamu povolených/blokovaných položek pro odhalená nasazení |\n| 📊 **Upravitelné limity rychlosti** | Konfigurovatelné globální/na úrovni poskytovatele limity s perzistencí |\n| 🔑 **Správa klíčů API a stanovení rozsahu** | Bezpečné vydávání/rotace klíčů a kontroly modelu/poskytovatele |\n| 🛡️ **Chráněné `/models`** | Volitelné ověřování a skrytí poskytovatele pro katalog modelů |\n\n### 📊 Pozorovatelnost a analytika\n\n| Funkce | Co to dělá |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| 📝 **Žádost + protokolování proxy** | Úplné protokolování požadavků/odpovědí a proxy |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Sjednocený panel protokolů** | Zobrazení požadavků, proxy, auditu a konzole na jedné stránce |\n| 🔍 **Vyžádat si telemetrii** | Latence p50/p95/p99 a trasování požadavků |\n| 🏥 **Panel zdraví** | Doba provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti |\n| 💰 **Sledování nákladů** | Kontrola rozpočtu a přehled o cenách pro jednotlivé modely |\n| 📈 **Analytické vizualizace** | Přehledy využití modelů/poskytovatelů a zobrazení trendů |\n| 🧪 **Rámec hodnocení** | Testování zlaté sady s konfigurovatelnými strategiemi shody |\n\n### ☁️ Nasazení a platforma\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| 🌐 **Nasazení kdekoli** | Localhost, VPS, Docker, cloudová prostředí |\n| 💾 **Synchronizace s cloudem** | Synchronizace konfigurace přes cloud worker |\n| 🔄 **Zálohování/Obnovení** | Toky exportu/importu a obnovy po havárii |\n| 🧙 **Průvodce nástupem** | Průvodce prvním spuštěním |\n| 🔧 **Panel nástrojů CLI** | Nastavení oblíbených kódovacích nástrojů jedním kliknutím |\n| 🎮 **Modelové hřiště** | Otestujte libovolného poskytovatele/model/koncový bod z řídicího panelu |\n| 🔏 **Přepínač otisků prstů v příkazovém řádku** | Porovnávání otisků prstů podle poskytovatele v Nastavení &gt; Zabezpečení |\n| 🌐 **i18n (30 jazyků)** | Plná jazyková podpora dashboardu a dokumentace s psaním zprava doleva |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Adresář vlastních dat** | Přepsání `DATA_DIR` pro umístění úložiště |\n\n### Hluboký pohled na funkce\n\n#### Chytrá záložní funkce s praktickou kontrolou nákladů\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyž selže kvóta, rychlost nebo stav, OmniRoute automaticky přejde k dalšímu kandidátovi bez nutnosti ručního přepínání.\n\n#### Správa protokolů, která je viditelná a ovladatelná\n\n- MCP + A2A jsou viditelné v uživatelském rozhraní a dokumentaci (nejsou skryté)\n- API pro stav protokolu zpřístupňují živá provozní data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnují akce pro operace 2. dne (přepínání kombinací, resetování jističů, zrušení úkolů)\n\n#### Pracovní postup překladatele + validace\n\nOblast překladatele zahrnuje:\n\n- **Hřiště** : kontroly transformace požadavků\n- **Tester chatu** : kompletní okružní cesta požadavku/odpovědi\n- **Testovací stolice** : více případů v jednom běhu\n- **Živý monitor** : zobrazení provozu v reálném čase\n\nPlus validace protokolu se skutečnými klienty pomocí `npm run test:protocols:e2e` .\n\n> 📖 **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** — Referenční informace o nástrojích, konfigurace IDE a příklady klientů\n>\n> 📖 **[Soubor README pro A2A Server](src/lib/a2a/README.md)** — Dovednosti, metody JSON-RPC, streamování a životní cyklus úloh\n\n## 🧪 Hodnocení (Evals)\n\nOmniRoute obsahuje vestavěný hodnotící rámec pro testování kvality odpovědí LLM v porovnání se zlatou sadou. Přístup k němu je možný přes **Analýzy → Hodnocení** v dashboardu.\n\n### Vestavěná zlatá sada\n\nPředinstalovaná sada „OmniRoute Golden Set“ obsahuje testovací případy pro:\n\n- Zdravím, matematika, zeměpis, generování kódu\n- Shoda s formátem JSON, překlad, generování markdownů\n- Bezpečnostní odmítnutí (škodlivý obsah), počítání, booleovská logika\n\n### Strategie hodnocení\n\n| Strategie | Popis | Příklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Výstup se musí přesně shodovat | `\"4\"` |\n| `contains` | Výstup musí obsahovat podřetězec (bez rozlišení velkých a malých písmen) | `\"Paris\"` |\n| `regex` | Výstup musí odpovídat vzoru regulárních výrazů | `\"1.*2.*3\"` |\n| `custom` | Vlastní JS funkce vrací true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Průvodce nastavením\n\n### Nastavení protokolu (MCP + A2A)\n\n<details>\n<summary><b>🧩 Nastavení MCP (Model Context Protocol)</b></summary>\n</details>\n\nSpuštění MCP transportu v režimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporučený postup ověření:\n\n1. Připojte svého MCP klienta přes stdio.\n2. Spusťte `omniroute_get_health` .\n3. Spusťte `omniroute_list_combos` .\n4. Otevřete `/dashboard/mcp` pro ověření prezenčního signálu, aktivity a auditu.\n\nUžitečná API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n<details>\n<summary><b>🤝 Nastavení A2A (Agent2Agent)</b></summary>\n</details>\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat úkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSpráva životního cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvozní uživatelské rozhraní:\n\n- `/dashboard/a2a` pro pozorovatelnost úloh/stavů/streamů a akce kouření\n\n<details>\n<summary><b>🧪 Komplexní validace protokolu</b></summary>\n</details>\n\nOvěřte oba protokoly se skutečnými klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTím se ověřuje:\n\n- Připojení/seznam/volání klienta MCP SDK\n- A2A objevování/odesílání/streamování/získávání/zrušení\n- Křížová kontrola dat v auditu MCP a API pro správu úloh A2A\n\n<details>\n<summary><b>💳 Poskytovatelé předplatného</b></summary>\n</details>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionály:** Pro složité úkoly používejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvótu pro každý model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Správa limitů účtu Codex (5h + týdně)\n\nKaždý účet Codex má nyní přepínače zásad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinového prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zásadu týdenního prahu okna.\n- Prahové chování: když povolené okno dosáhne využití &gt;=90 %, je daný účet přeskočen.\n- Chování rotace: OmniRoute automaticky přesměruje na další způsobilý účet Codex.\n- Chování při resetování: Po `resetAt` určité doby se účet automaticky opět stane způsobilým.\n\nScénáře:\n\n- `5h ON` + `Weekly ON` : účet je přeskočen, když kterékoli z oken dosáhne prahové hodnoty.\n- `5h OFF` + `Weekly ON` : účet může být zablokován pouze týdenním používáním.\n- `5h ON` + `Weekly OFF` : účet může být zablokován pouze při 5hodinovém používání.\n- `resetAt` passed: účet se automaticky znovu zapne (bez ručního opětovného povolení).\n\n### Gemini CLI (ZDARMA 180 000/měsíc!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepší hodnota:** Obrovská bezplatná úroveň! Použijte ji před placenými úrovněmi.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n<details>\n<summary><b>🔑 Poskytovatelé klíčů API</b></summary>\n</details>\n\n### NVIDIA NIM (BEZPLATNÝ přístup pro vývojáře — více než 70 modelů)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Získejte zdarma klíč API (včetně 1000 inferenčních kreditů)\n3. Ovládací panel → Přidat poskytovatele → NVIDIA NIM:\n - Klíč API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a více než 50 dalších\n\n**Tip pro profesionály:** API kompatibilní s OpenAI – funguje bez problémů s překladem formátů OmniRoute!\n\n### Hluboké vyhledávání\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatná úroveň!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Získejte klíč API (včetně bezplatné úrovně)\n3. Ovládací panel → Přidat poskytovatele → Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionály:** Ultrarychlá inference – nejlepší pro kódování v reálném čase!\n\n### OpenRouter (100+ modelů)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → OpenRouter\n\n**Modely:** Získejte přístup k více než 100 modelům od všech hlavních poskytovatelů prostřednictvím jediného klíče API.\n\n<details>\n<summary><b>💰 Levní poskytovatelé (záložní)</b></summary>\n</details>\n\n### GLM-4.7 (Denní reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Získejte klíč API z kódovacího plánu\n3. Nástěnka → Přidat klíč API:\n - Poskytovatel: `glm`\n - Klíč API: `your-key`\n\n**Použití:** `glm/glm-4.7`\n\n**Tip pro profesionály:** Programovací plán nabízí 3× kvótu za cenu 1/7! Obnovuje se denně v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionály:** Nejlevnější varianta pro dlouhý kontext (1 milion tokenů)!\n\n### Kimi K2 (paušální poplatek 9 dolarů měsíčně)\n\n1. Odebírat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `kimi/kimi-latest`\n\n**Tip pro profesionály:** Fixních 9 $/měsíc za 10 milionů tokenů = efektivní náklady 0,90 $/1 milion!\n\n<details>\n<summary><b>🆓 BEZPLATNÍ poskytovatelé (nouzové zálohování)</b></summary>\n</details>\n\n### Qoder (5 BEZPLATNÝCH modelů přes OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kódem zařízení)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n<details>\n<summary><b>🎨 Vytvořte kombinace</b></summary>\n</details>\n\n### Příklad 1: Maximalizace předplatného → Levné zálohování\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Příklad 2: Pouze zdarma (nulové náklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n<details>\n<summary><b>🔧 Integrace s rozhraním příkazového řádku</b></summary>\n</details>\n\n### IDE kurzoru\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jedním kliknutím použijte stránku **Nástroje CLI** na řídicím panelu nebo ručně upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Možnost 1 – Dashboard (doporučeno):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Možnost 2 – Manuální úprava:** Úprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznámka:** OpenClaw funguje pouze s lokálním OmniRoute. Místo `localhost` použijte `127.0.0.1` , abyste se vyhnuli problémům s rozlišením IPv6.\n\n### Cline / Pokračovat / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Přidání OmniRoute jako vlastního poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvořte/upravte `opencode.json` v kořenovém adresáři projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` přidejte jakýkoli model dostupný ve vašem koncovém bodu OmniRoute `/v1/models` . Použijte formát `provider/model-id` z vašeho dashboardu OmniRoute.\n\n---\n\n## 🐛 Řešení problémů\n\n<details>\n<summary><b>Kliknutím rozbalíte průvodce řešením problémů</b></summary>\n</details>\n\n**\"Jazykový model neposkytoval zprávy\"**\n\n- Kvóta poskytovatele vyčerpána → Zkontrolujte sledování kvót na řídicím panelu\n- Řešení: Použijte záložní kombinovanou variantu nebo přejděte na levnější úroveň\n\n**Omezení rychlosti**\n\n- Kvóta předplatného vyčerpána → Přechod na GLM/MiniMax\n- Přidat kombo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vypršela**\n\n- Automaticky aktualizováno službou OmniRoute\n- Pokud problémy přetrvávají: Ovládací panel → Poskytovatel → Znovu připojit\n\n**Vysoké náklady**\n\n- Zkontrolujte statistiky využití v sekci Nástěnka → Náklady\n- Přepnout primární model na GLM/MiniMax\n- Pro nekritické úlohy použijte bezplatnou úroveň (Gemini CLI, Qoder).\n\n**Porty řídicího panelu/API jsou nesprávné**\n\n- `PORT` je kanonický základní port (a standardně port API)\n- `API_PORT` přepisuje pouze posluchač API kompatibilní s OpenAI.\n- `DASHBOARD_PORT` přepisuje pouze posluchač dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaši veřejnou URL adresu řídicího panelu (pro zpětná volání OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ověřte, zda `BASE_URL` odkazuje na vaši spuštěnou instanci.\n- Ověřte, zda `CLOUD_URL` odkazuje na váš očekávaný cloudový koncový bod.\n- Udržujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na straně serveru.\n\n**První přihlášení nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud není nastaveno, záložní heslo je `123456`\n\n**Žádné protokoly požadavků**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test připojení ukazuje „Neplatné“ pro poskytovatele kompatibilní s OpenAI**\n\n- Mnoho poskytovatelů nezpřístupňuje koncový bod `/models`\n- OmniRoute v1.0.6+ zahrnuje záložní ověření pomocí dokončení chatu\n- Zajistěte, aby základní URL adresa obsahovala příponu `/v1`\n\n### 🔐 OAuth na vzdáleném serveru\n\n<a name=\"oauth-on-a-remote-server\"></a>\n\n> **⚠️ Důležité pro uživatele, kteří provozují OmniRoute na VPS, Dockeru nebo jakémkoli vzdáleném serveru**\n\n#### Proč selhává OAuth v rozhraní CLI Antigravity / Gemini na vzdálených serverech?\n\nPoskytovatelé rozhraní CLI **Antigravity** a **Gemini** používají **Google OAuth 2.0** . Google vyžaduje, aby se `redirect_uri` v toku OAuth přesně shodoval s jedním z předregistrovaných URI v konzoli Google Cloud Console aplikace.\n\nPřihlašovací údaje OAuth, které jsou součástí OmniRoute, jsou registrovány **pouze pro `localhost`** . Když přistupujete k OmniRoute na vzdáleném serveru (např. `https://omniroute.myserver.com` ), Google odmítne ověření pomocí:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Řešení: Nakonfigurujte si vlastní přihlašovací údaje OAuth\n\nV Google Cloud Console je potřeba vytvořit **ID klienta OAuth 2.0** s URI vašeho serveru.\n\n#### Krok za krokem\n\n**1. Otevřete konzoli Google Cloud**\n\nPřejděte na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvořte nové ID klienta OAuth 2.0**\n\n- Klikněte na **„+ Vytvořit přihlašovací údaje“** → **„ID klienta OAuth“**\n- Typ aplikace: **„Webová aplikace“**\n- Název: cokoli chcete (např. `OmniRoute Remote` )\n\n**3. Přidejte autorizované URI pro přesměrování**\n\nDo pole **„Autorizované identifikátory URI pro přesměrování“** přidejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraďte `your-server.com` doménou nebo IP adresou vašeho serveru (v případě potřeby uveďte i port, např. `http://45.33.32.156:20128/callback` ).\n\n**4. Uložte a zkopírujte přihlašovací údaje**\n\nPo vytvoření Google zobrazí **ID klienta** a **tajný kód klienta** .\n\n**5. Nastavení proměnných prostředí**\n\nVe vašem souboru `.env` (nebo proměnných prostředí Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu připojit**\n\nŘídicí panel → Poskytovatelé → Antigravity (nebo Gemini CLI) → OAuth\n\nGoogle nyní bude správně přesměrovávat na `https://your-server.com/callback` .\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nPokud si teď nechcete nastavovat vlastní přihlašovací údaje, můžete stále použít **ruční postup pro URL** :\n\n1. OmniRoute otevírá autorizační URL od Googlu\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru).\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče (i když se stránka nenačte)\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute.\n5. Klikněte na **„Připojit“**\n\n> To funguje, protože autorizační kód v URL adrese je platný bez ohledu na to, zda se načetla přesměrovací stránka.\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nChcete-li získat přístup k přihlašovacím údajům bez vlastní konfigurace, můžete použít následující postup:\n\n1. OmniRoute otevře URL autorizace Google\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru)\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute\n5. Klikněte na **„Připojit\"**\n\n> Toto řešení funguje, protože autorizační kód v URL adrese je platný bez ohledu na načtení přesměrovací stránky.\n\n---\n\n## 🛠️ Technologický stack\n\n<details>\n<summary><b>Kliknutím rozbalíte podrobnosti o technologickém stacku</b></summary>\n</details>\n\n- **Runtime** : Node.js 18–22 LTS (⚠️ Node.js 24+ **není podporován** — nativní binární soubory `better-sqlite3` jsou nekompatibilní)\n- **Jazyk** : TypeScript 5.9 — **100% TypeScript** napříč `src/` a `open-sse/` ( `any` v základních modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databáze** : LowDB (JSON) + SQLite (stav domény + protokoly proxy + audit MCP + rozhodnutí o směrování)\n- **Schémata** : Zod (validace I/O nástrojů MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamování** : Události odeslané serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klíče + autorizace s rozsahem MCP\n- **Testování** : Node.js test runner + Vitest (900+ testů včetně unit, integračních, E2E)\n- **CI/CD** : Akce GitHubu (automatické publikování v npm + Docker Hub při vydání)\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **Balíček** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistič, exponenciální odstavení, ochrana proti hromům, falešné TLS, automatické kombinované samoopravování\n\n---\n\n## 📖 Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uživatelská příručka](docs/USER_GUIDE.md) | Poskytovatelé, kombinace, integrace CLI, nasazení |\n| [Referenční informace k API](docs/API_REFERENCE.md) | Všechny koncové body s příklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nástrojů MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamování, správa úloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorové bodování, balíčky režimů, samoléčba |\n| [Odstraňování problémů](docs/TROUBLESHOOTING.md) | Běžné problémy a jejich řešení |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a interní prvky systému |\n| [Přispívání](CONTRIBUTING.md) | Nastavení a pokyny pro vývoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpečnostní zásady](SECURITY.md) | Hlášení zranitelností a bezpečnostní postupy |\n| [Nasazení virtuálního počítače](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletní průvodce: Nastavení virtuálního počítače + nginx + Cloudflare |\n| [Galerie funkcí](docs/FEATURES.md) | Vizuální prohlídka řídicího panelu se snímky obrazovky |\n| [Kontrolní seznam vydání](docs/RELEASE_CHECKLIST.md) | Kroky ověření před vydáním |\n\n---\n\n## 🗺️ Plán\n\nOmniRoute má **v plánu více než 210 funkcí** v několika fázích vývoje. Zde jsou klíčové oblasti:\n\n| Kategorie | Plánované funkce | Hlavní body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| 🧠 **Směrování a inteligence** | 25+ | Směrování s nejnižší latencí, směrování založené na tagech, kontrola kvót před výstupem, výběr účtu P2C |\n| 🔒 **Zabezpečení a dodržování předpisů** | 20+ | Zpevnění SSRF, maskování přihlašovacích údajů, limit rychlosti pro každý koncový bod, stanovení rozsahu klíčů pro správu |\n| 📊 **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledování kvót v reálném čase, sledování nákladů podle modelu |\n| 🔄 **Integrace poskytovatelů** | 20+ | Dynamický registr modelů, doba zchlazení poskytovatelů, Codex pro více účtů, analýza kvót Copilota |\n| ⚡ **Výkon** | 15+ | Dvojitá vrstva mezipaměti, mezipaměť výzev, mezipaměť odpovědí, udržování streamování, dávkové API |\n| 🌐 **Ekosystém** | 10+ | WebSocket API, horké opětovné načítání konfigurace, distribuované úložiště konfigurace, komerční režim |\n\n### 🔜 Již brzy\n\n- 🔗 **Integrace OpenCode** — Nativní podpora poskytovatelů pro IDE kódování s AI v OpenCode\n- 🔗 **Integrace TRAE** — Plná podpora vývojového rámce TRAE pro umělou inteligenci\n- 📦 **Dávkové API** — Asynchronní dávkové zpracování hromadných požadavků\n- 🎯 **Směrování na základě tagů** — Směrování požadavků na základě vlastních tagů a metadat\n- 💰 **Strategie nejnižších nákladů** – Automaticky vybere nejlevnějšího dostupného poskytovatele\n\n> 📝 Úplné specifikace funkcí jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobných specifikací)\n\n---\n\n## 👥 Přispěvatelé\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Přispěvatelé](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak přispět\n\n1. Vytvoření forku repozitáře\n2. Vytvořte si vlastní větev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrďte změny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do větve ( `git push origin feature/amazing-feature` )\n5. Otevřít žádost o změny (pull request)\n\nPodrobné pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydání nové verze\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Hvězdná historie\n\n## Hvězdáři v průběhu času\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvězdáři v průběhu času](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## 🙏 Poděkování\n\nZvláštní poděkování patří **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** – původnímu projektu, který inspiroval tento fork. OmniRoute staví na tomto neuvěřitelném základu s dalšími funkcemi, multimodálními API a kompletním přepsáním TypeScriptu.\n\nZvláštní poděkování patří **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – původní implementaci Go, která inspirovala tento JavaScriptový port.\n\n---\n\n## 📄 Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n<div align=\"center\">\n <sub>Vytvořeno s ❤️ pro vývojáře, kteří programují 24 hodin denně, 7 dní v týdnu</sub>\n <br>\n <sub><p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\">omniroute.online</a></p></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "b84e79362ea2195307dc36fff8a4f2dec5b203d0": {"t": 1785764459.1759288, "n": 92692, "h": "80ca04f6e2160f90", "c": "# 🚀 OmniRoute — Bezplatná brána umělé inteligence\n\n### Nikdy nepřestávejte s kódováním. Chytré směrování k **BEZPLATNÝM a levným modelům AI** s automatickým přepínáním mezi záložními systémy.\n\n_Váš univerzální API proxy – jeden endpoint, více než 44 poskytovatelů, nulové výpadky. Nyní s orchestrací agentů **MCP a A2A** ._\n\n**Dokončení chatu • Vkládání • Generování obrázků • Video • Hudba • Audio • Změna pořadí • **Vyhledávání na webu** • MCP server • A2A protokol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n</div>\n<p data-md-type=\"paragraph\"><a href=\"https://www.npmjs.com/package/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/npm/v/omniroute?color=cb3837&amp;logo=npm\" alt=\"verze npm\" data-md-type=\"image\"><a href=\"https://hub.docker.com/r/diegosouzapw/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&amp;logo=docker&amp;color=2496ED\" alt=\"Docker Hub\" data-md-type=\"image\"><a href=\"https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/github/license/diegosouzapw/OmniRoute\" alt=\"Licence\" data-md-type=\"image\"><a href=\"https://omniroute.online\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&amp;logoColor=white\" alt=\"Webové stránky\" data-md-type=\"image\"><a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&amp;logoColor=white\" alt=\"WhatsApp\" data-md-type=\"image\"></p>\n<p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\" data-md-type=\"link\">🌐 Webové stránky</a> • <a href=\"#-quick-start\" data-md-type=\"link\">🚀 Rychlý start</a> • <a href=\"#-key-features\" data-md-type=\"link\">💡 Funkce</a> • <a href=\"#-documentation\" data-md-type=\"link\">📖 Dokumentace</a> • <a href=\"#-pricing-at-a-glance\" data-md-type=\"link\">💰 Ceník</a> • <a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\">💬 WhatsApp</a></p>\n<div data-md-type=\"block_html\"></div>\n\n🌐 **Dostupné v:** 🇺🇸 [Angličtina](README.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [maďarština](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonésie](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nizozemsko](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)\n\n---\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| ------------------------------- | --------------------------------------------------------------------------------- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n## 🖼️ Hlavní ovládací panel\n\n<div align=\"center\"> <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"Řídicí panel OmniRoute\" width=\"800\"> </div>\n\n---\n\n## 📸 Náhled řídicího panelu\n\n<details>\n<summary><b>Kliknutím zobrazíte snímky obrazovky z řídicího panelu</b></summary>\n</details>\n\n| Strana | Snímek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelé** | ![Poskytovatelé](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdraví** | ![Zdraví](docs/screenshots/04-health.png) |\n| **Překladatel** | ![Překladatel](docs/screenshots/05-translator.png) |\n| **Nastavení** | ![Nastavení](docs/screenshots/06-settings.png) |\n| **Nástroje CLI** | ![Nástroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly používání** | ![Používání](docs/screenshots/08-usage.png) |\n| **Koncové body** | ![Koncové body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### 🤖 Bezplatný poskytovatel umělé inteligence pro vaše oblíbené programátory\n\n_Připojte libovolný nástroj IDE nebo CLI s umělou inteligencí přes OmniRoute — bezplatnou API bránu pro neomezené kódování._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openclaw/openclaw\"><img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"><br><b>OpenClaw</b></a><br> <sub>⭐ 205 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/HKUDS/nanobot\"><img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"><br><b>NanoBot</b></a><br> <sub>⭐ 20,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/sipeed/picoclaw\"><img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"><br><b>PicoClaw</b></a><br> <sub>⭐ 14,6 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/zeroclaw-labs/zeroclaw\"><img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"><br><b>ZeroClaw</b></a><br> <sub>⭐ 9,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/nearai/ironclaw\"><img src=\"./public/providers/ironclaw.png\" alt=\"Železný dráp\" width=\"48\"><br><b>Železný dráp</b></a><br> <sub>⭐ 2,1 tisíce</sub> </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anomalyco/opencode\"><img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"><br><b>OpenCode</b></a><br> <sub>⭐ 106 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openai/codex\"><img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"><br><b>Codex CLI</b></a><br> <sub>⭐ 60,8 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anthropics/claude-code\"><img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"><br><b>Claude Code</b></a><br> <sub>⭐ 67,3 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/google-gemini/gemini-cli\"><img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"><br> <b>Gemini CLI</b></a><br> <sub>⭐ 94,7 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/Kilo-Org/kilocode\"><img src=\"./public/providers/kilocode.png\" alt=\"Kilo kód\" width=\"48\"><br><b>Kilo kód</b></a><br> <sub>⭐ 15,5 tisíc</sub> </td>\n </tr>\n </table>\n\n<sub>📡 Všichni agenti se připojují přes <code>http://localhost:20128/v1</code> nebo <code>http://cloud.omniroute.online/v1</code> — jedna konfigurace, neomezené modely a kvóty</sub>\n\n---\n\n## 🤔 Proč OmniRoute?\n\n**Přestaňte plýtvat penězi a narážet na limity:**\n\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Kvóta předplatného vyprší každý měsíc\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Limity rychlosti vám zabrání v kódování\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Drahá API (20–50 USD/měsíc na poskytovatele)\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Ruční přepínání mezi poskytovateli\n\n**OmniRoute to řeší:**\n\n- ✅ **Maximalizujte předplatné** – Sledujte kvótu, využijte každou částku před resetováním\n- ✅ **Automatické záložní** – Předplatné → API klíč → Levné → Zdarma, žádné výpadky\n- ✅ **Více účtů** – Round-robin mezi účty u jednotlivých poskytovatelů\n- ✅ **Univerzální** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakýmkoli nástrojem CLI\n\n---\n\n## 📧 Podpora\n\n> 💬 **Přidejte se k naší komunitě!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získejte pomoc, sdílejte tipy a buďte v obraze.\n\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problémy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitní skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Přispívání** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevřete žádost o příspěvek nebo si vyberte `good first issue`\n- **Původní projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### 🐛 Hlásíte chybu?\n\nPři otevírání problému spusťte příkaz system-info a přiložte vygenerovaný soubor:\n\n```bash\nnpm run system-info\n```\n\nTím se vygeneruje soubor `system-info.txt` s verzí Node.js, verzí OmniRoute, podrobnostmi o operačním systému, nainstalovanými nástroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systémovými balíčky – vše, co potřebujeme k rychlé reprodukci vašeho problému. Soubor přiložte přímo k vašemu problému na GitHubu.\n\n---\n\n## 🔄 Jak to funguje\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 Co řeší OmniRoute — 30 skutečných problémů a případů použití\n\n> **Každý vývojář používající nástroje umělé inteligence se s těmito problémy setkává denně.** OmniRoute byl vytvořen tak, aby je všechny vyřešil – od překročení nákladů po regionální bloky, od nefunkčních toků OAuth až po operace s protokoly a sledovatelnost v podniku.\n\n<details>\n<summary><b>💸 1. „Platím si drahé předplatné, ale stále mě ruší limity“</b></summary>\n</details>\n\nVývojáři platí za Claude Pro, Codex Pro nebo GitHub Copilot 20–200 dolarů měsíčně. I při platbě má kvóta strop – 5 hodin používání, týdenní limity nebo limity rychlosti za minutu. Uprostřed kódovací relace poskytovatel přestane reagovat a vývojář ztrácí plynulost a produktivitu.\n\n**Jak to OmniRoute řeší:**\n\n- **Inteligentní čtyřúrovňová záložní služba** – Pokud dojde kvóta předplatného, ​​automaticky se přesměruje na API klíč → Levné → Zdarma bez manuálního zásahu\n- **Sledování kvót v reálném čase** – Zobrazuje spotřebu tokenů v reálném čase s odpočítáváním resetování (5 hodin, denně, týdně)\n- **Podpora více účtů** – Více účtů u jednoho poskytovatele s automatickým přepínáním – když jeden dojde, přepne se na další\n- **Vlastní kombinace** — Přizpůsobitelné záložní řetězce se 6 strategiemi vyvažování (fill-first, round robin, P2C, náhodné, nejméně používané, nákladově optimalizované)\n- **Codex Business Quotas** — Sledování kvót pracovního prostoru firmy/týmu přímo v dashboardu\n\n<details>\n<summary><b>🔌 2. „Potřebuji použít více poskytovatelů, ale každý má jiné API“</b></summary>\n</details>\n\nOpenAI používá jeden formát, Claude (Anthropic) jiný a Gemini ještě třetí. Pokud chce vývojář testovat modely od různých poskytovatelů nebo mezi nimi přecházet, musí překonfigurovat SDK, změnit koncové body a vypořádat se s nekompatibilními formáty. Vlastní poskytovatelé (FriendLI, NIM) mají nestandardní koncové body modelů.\n\n**Jak to OmniRoute řeší:**\n\n- **Sjednocený koncový bod** — Jeden `http://localhost:20128/v1` slouží jako proxy pro všech 67+ poskytovatelů.\n- **Překlad formátu** — Automatický a transparentní: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Sanitizace odpovědí** — Odstraňuje nestandardní pole ( `x_groq` , `usage_breakdown` , `service_tier` ), která porušují OpenAI SDK v1.83+\n- **Normalizace rolí** — Převádí `developer` → `system` pro poskytovatele bez OpenAI; `system` → `user` pro GLM/ERNIE\n- **Extrakce tagů Think** — Extrahuje bloky `<think>` z modelů, jako je DeepSeek R1, do standardizovaného `reasoning_content`\n- **Strukturovaný výstup pro Gemini** — `json_schema` → automatická konverze `responseMimeType` / `responseSchema`\n- **Výchozí hodnota `stream` je `false`** – Odpovídá specifikaci OpenAI, čímž se zabrání neočekávanému SSE v Python/Rust/Go SDK.\n\n<details>\n<summary><b>🌐 3. „Můj poskytovatel AI blokuje můj region/zemi“</b></summary>\n</details>\n\nPoskytovatelé jako OpenAI/Codex blokují přístup z určitých geografických oblastí. Uživatelé se během připojení OAuth a API dostávají k chybám jako `unsupported_country_region_territory` . To je obzvláště frustrující pro vývojáře z rozvojových zemí.\n\n**Jak to OmniRoute řeší:**\n\n- **3úrovňová konfigurace proxy** – Konfigurovatelná proxy na 3 úrovních: globální (veškerý provoz), pro jednotlivé poskytovatele (pouze jeden poskytovatel) a pro jednotlivé připojení/klíč\n- **Barevně kódované odznaky proxy** – Vizuální indikátory: 🟢 globální proxy, 🟡 proxy poskytovatele, 🔵 proxy připojení, vždy zobrazující IP adresu\n- **Výměna tokenů OAuth prostřednictvím proxy** – tok OAuth také prochází přes proxy, čímž se řeší `unsupported_country_region_territory`\n- **Testy připojení přes proxy** – Testy připojení používají nakonfigurovaný proxy (již žádné přímé obcházení)\n- **Podpora SOCKS5** — Plná podpora proxy SOCKS5 pro odchozí směrování\n- **TLS Fingerprint Spoofing** — Otisk prstu TLS podobný prohlížeči pomocí `wreq-js` pro obcházení detekce botů\n- **🔏 Porovnávání otisků prstů v CLI** — Změní pořadí záhlaví a polí v těle serveru tak, aby odpovídala nativním binárním podpisům v CLI, čímž drasticky snižuje riziko nahlašování účtu. IP adresa proxy je zachována — získáte současně stealth **i** maskování IP adresy.\n\n<details>\n<summary><b>🆓 4. „Chci používat umělou inteligenci pro kódování, ale nemám peníze“</b></summary>\n</details>\n\nNe každý si může dovolit zaplatit 20–200 dolarů měsíčně za předplatné AI. Studenti, vývojáři z rozvíjejících se zemí, amatéři a freelanceři potřebují přístup ke kvalitním modelům za nulovou cenu.\n\n**Jak to OmniRoute řeší:**\n\n- **Vestavění poskytovatelé bezplatné úrovně** — Nativní podpora pro 100% bezplatné poskytovatele: iFlow (5 neomezených modelů přes OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezené modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisíc tokenů/měsíc zdarma)\n- **Ollama Cloud** — Cloudově hostované modely Ollama na `api.ollama.com` s bezplatnou úrovní „Light usage“; použijte prefix `ollamacloud/<model>`\n- **Kombinace pouze zdarma** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/měsíc s nulovými prostoji\n- **NVIDIA NIM Free Access** — ~40 RPM developerský přístup k více než 70 modelům na build.nvidia.com (přechod z kreditů na čisté limity rychlosti)\n- **Strategie optimalizace nákladů** – Strategie směrování, která automaticky vybere nejlevnějšího dostupného poskytovatele\n\n<details>\n<summary><b>🔒 5. „Potřebuji chránit svou bránu umělé inteligence před neoprávněným přístupem“</b></summary>\n</details>\n\nPři zpřístupnění brány umělé inteligence síti (LAN, VPS, Docker) může kdokoli s adresou spotřebovat tokeny/kvótu vývojáře. Bez ochrany jsou API zranitelná vůči zneužití, prompt injection a dalšímu zneužití.\n\n**Jak to OmniRoute řeší:**\n\n- **Správa klíčů API** – generování, rotace a vymezování rozsahu pro každého poskytovatele s vyhrazenou stránkou `/dashboard/api-manager`\n- **Oprávnění na úrovni modelu** – Omezení klíčů API na konkrétní modely ( `openai/*` , zástupné znaky) pomocí přepínače Povolit vše/Omezit\n- **Ochrana koncových bodů API** – Vyžaduje klíč pro `/v1/models` a blokuje konkrétní poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** — Všechny trasy dashboardu chráněné middlewarem `withAuth` + tokeny CSRF\n- **Omezovač rychlosti** — Omezování rychlosti na IP s konfigurovatelnými okny\n- **Filtrování IP adres** — Seznam povolených/blokovaných adres pro řízení přístupu\n- **Ochrana proti vkládání výzev** – Sanitizace proti škodlivým vzorcům výzev\n- **Šifrování AES-256-GCM** – přihlašovací údaje jsou v klidovém stavu šifrovány\n\n<details>\n<summary><b>🛑 6. „Můj poskytovatel selhal a já ztratil/a programovací tok“</b></summary>\n</details>\n\nPoskytovatelé umělé inteligence se mohou stát nestabilními, vracet chyby 5xx nebo dosáhnout dočasných limitů rychlosti. Pokud je vývojář závislý na jediném poskytovateli, je jeho práce přerušena. Bez jističů může opakované pokusy vést k pádu aplikace.\n\n**Jak to OmniRoute řeší:**\n\n- **Jistič pro každý model** – Automatické otevírání/zavírání s konfigurovatelnými prahovými hodnotami a dobou ochlazování (Zavřeno/Otevřeno/Poloviční otevření), rozsah definovaný pro každý model, aby se zabránilo kaskádování bloků\n- **Exponenciální odklad** — Progresivní zpoždění opakování\n- **Anti-Thundering Herd** — ochrana Mutex + semafor proti souběžným bouřím s opakovanými pokusy\n- **Kombinované záložní řetězce** – Pokud primární poskytovatel selže, automaticky se propadne řetězcem bez zásahu.\n- **Kombinovaný jistič** – Automaticky deaktivuje selhávajícího poskytovatele v rámci kombinovaného řetězce\n- **Dashboard stavu** — Monitorování provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti, latence p50/p95/p99\n\n<details>\n<summary><b>🔧 7. „Konfigurace každého nástroje umělé inteligence je zdlouhavá a opakující se“</b></summary>\n</details>\n\nVývojáři používají Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Každý nástroj potřebuje jinou konfiguraci (API endpoint, klíč, model). Překonfigurování při změně poskytovatele nebo modelu je ztráta času.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel nástrojů CLI** — Vyhrazená stránka s nastavením jedním kliknutím pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generátor konfigurace GitHub Copilot** – Generuje `chatLanguageModels.json` pro VS Code s hromadným výběrem modelu\n- **Průvodce zaváděním** – 4krokové nastavení pro začínající uživatele\n- **Jeden koncový bod, všechny modely** – jednou nakonfigurujte `http://localhost:20128/v1` a získejte přístup k více než 44 poskytovatelům\n\n<details>\n<summary><b>🔑 8. „Správa OAuth tokenů od více poskytovatelů je peklo“</b></summary>\n</details>\n\nClaude Code, Codex, Gemini CLI, Copilot – všechny používají OAuth 2.0 s tokeny s vypršením platnosti. Vývojáři se musí neustále znovu autentizovat, řešit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdálených serverech. Obzvláště problematický je OAuth v LAN/VPS.\n\n**Jak to OmniRoute řeší:**\n\n- **Automatická aktualizace tokenů** – Tokeny OAuth se obnovují na pozadí před vypršením platnosti.\n- **Vestavěný OAuth 2.0 (PKCE)** – Automatický tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** — Více účtů na poskytovatele prostřednictvím extrakce tokenů JWT/ID\n- **OAuth LAN/Remote Fix** — Detekce privátní IP adresy pro `redirect_uri` + manuální režim URL pro vzdálené servery\n- **OAuth Behind Nginx** — Používá `window.location.origin` pro kompatibilitu s reverzní proxy\n- **Průvodce vzdáleným OAuth** – Podrobný návod k přihlašovacím údajům Google Cloud na VPS/Dockeru\n\n<details>\n<summary><b>📊 9. „Nevím, kolik utrácím ani kde“</b></summary>\n</details>\n\nVývojáři používají více placených poskytovatelů, ale nemají jednotný přehled o výdajích. Každý poskytovatel má svůj vlastní fakturační panel, ale neexistuje žádný konsolidovaný přehled. Mohou se hromadit neočekávané náklady.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard pro analýzu nákladů** – Sledování nákladů na token a správa rozpočtu pro každého poskytovatele\n- **Rozpočtové limity na úroveň** – Strop výdajů na úroveň, který spouští automatický záložní režim\n- **Konfigurace cen podle modelu** – Konfigurovatelné ceny podle modelu\n- **Statistiky použití pro každý klíč API** — Počet požadavků a časové razítko posledního použití pro každý klíč\n- **Analytický panel** – Statistické karty, graf využití modelu, tabulka poskytovatelů s mírou úspěšnosti a latencí\n\n<details>\n<summary><b>🐛 10. „Nedokážu diagnostikovat chyby a problémy ve volání umělé inteligence.“</b></summary>\n</details>\n\nKdyž volání selže, vývojář neví, zda se jednalo o limit rychlosti, vypršelý token, špatný formát nebo chybu poskytovatele. Fragmentované protokoly napříč různými terminály. Bez sledovatelnosti je ladění metodou pokus-omyl.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel jednotných protokolů** – 4 karty: Protokoly požadavků, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlížeč protokolů konzole** — Prohlížeč protokolů v reálném čase ve stylu terminálu s barevně kódovanými úrovněmi, automatickým posouváním, vyhledáváním a filtrováním\n- **Protokoly proxy SQLite** – trvalé protokoly, které přežijí restart serveru\n- **Překladačské hřiště** — 4 režimy ladění: Hřiště (překlad formátu), Tester chatu (okružní), Testovací stůl (dávkový), Živý monitor (v reálném čase)\n- **Telemetrie požadavků** — latence p50/p95/p99 + trasování X-Request-Id\n- **Souborové protokolování s rotací** – Konzolový interceptor zachycuje vše do protokolu JSON s rotací na základě velikosti\n- **Zpráva o systémových informacích** — příkaz `npm run system-info` vygeneruje `system-info.txt` s kompletním popisem vašeho prostředí (verze uzlu, verze OmniRoute, operační systém, nástroje CLI, stav Dockeru/PM2). Přiložte jej při hlášení problémů pro okamžité třídění.\n\n<details>\n<summary><b>🏗️ 11. „Nasazení a údržba brány je složitá“</b></summary>\n</details>\n\nInstalace, konfigurace a údržba AI proxy v různých prostředích (lokální, VPS, Docker, cloud) je pracná. Problémy, jako jsou pevně zakódované cesty, `EACCES` u adresářů, konflikty portů a multiplatformní sestavení, přispívají k obtížím.\n\n**Jak to OmniRoute řeší:**\n\n- **npm globální instalace** — `npm install -g omniroute && omniroute` — hotovo\n- **Docker Multi-Platform** — AMD64 + nativní ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** — `base` (bez nástrojů CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopová aplikace Electron** — Nativní aplikace pro Windows/macOS/Linux se systémovou lištou, automatickým spuštěním a offline režimem\n- **Režim rozdělených portů** – API a řídicí panel na samostatných portech pro pokročilé scénáře (reverzní proxy, síťování kontejnerů)\n- **Cloud Sync** – Konfigurace synchronizace mezi zařízeními pomocí Cloudflare Workers\n- **Zálohy databází** — Automatické zálohování, obnovení, export a import všech nastavení\n\n<details>\n<summary><b>🌍 12. „Rozhraní je pouze v angličtině a můj tým nemluví anglicky“</b></summary>\n</details>\n\nTýmy v neanglicky mluvících zemích, zejména v Latinské Americe, Asii a Evropě, se potýkají s rozhraními pouze v angličtině. Jazykové bariéry snižují míru přijetí a zvyšují chyby v konfiguraci.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard i18n — 30 jazyků** — Všech 500+ kláves je přeloženo včetně arabštiny, bulharštiny, dánštiny, němčiny, španělštiny, finštiny, francouzštiny, hebrejštiny, hindštiny, maďarštiny, indonéštiny, italštiny, japonštiny, korejštiny, malajštiny, holandštiny, norštiny, polštiny, portugalštiny (PT/BR), rumunštiny, ruštiny, slovenštiny, švédštiny, thajštiny, ukrajinštiny, vietnamštiny, čínštiny, filipínštiny a angličtiny\n- **Podpora RTL** – Podpora psaní zprava doleva pro arabštinu a hebrejštinu\n- **Vícejazyčné soubory README** — 30 kompletních překladů dokumentace\n- **Výběr jazyka** — Ikona glóbu v záhlaví pro přepínání v reálném čase\n\n<details>\n<summary><b>🔄 13. „Potřebuji víc než jen chat – potřebuji vložené soubory, obrázky, zvuk.“</b></summary>\n</details>\n\nUmělá inteligence není jen dokončování chatu. Vývojáři potřebují generovat obrázky, přepisovat zvuk, vytvářet embeddedy pro RAG, měnit pořadí dokumentů a moderovat obsah. Každé API má jiný koncový bod a formát.\n\n**Jak to OmniRoute řeší:**\n\n- **Vkládání** — `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generování obrázků** — `/v1/images/generations` s 10 poskytovateli a více než 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Převod textu na video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Převod textu na hudbu** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Přepis zvuku** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Převod textu na řeč** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a další stávající poskytovatelé\n- **Moderování** — `/v1/moderations` — Kontroly bezpečnosti obsahu\n- **Změna pořadí** — `/v1/rerank` — Změna pořadí relevance dokumentu\n- **Responses API** — Plná podpora `/v1/responses` pro Codex\n\n<details>\n<summary><b>🧪 14. „Nemám způsob, jak testovat a porovnávat kvalitu napříč modely.“</b></summary>\n</details>\n\nVývojáři chtějí vědět, který model je pro jejich případ použití nejlepší – kód, překlad, uvažování – ale ruční porovnávání je pomalé. Neexistují žádné integrované nástroje pro vyhodnocování.\n\n**Jak to OmniRoute řeší:**\n\n- **Hodnocení LLM** — Testování Golden setu s 10 předinstalovanými případy zahrnujícími pozdravy, matematiku, geografii, generování kódu, dodržování JSON, překlad, markdown, odmítnutí bezpečnostních požadavků\n- **4 strategie shody** — `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovací lavice pro překladatelské hřiště** — Dávkové testování s více vstupy a očekávanými výstupy, porovnání napříč poskytovateli\n- **Tester chatu** — Kompletní okružní cesta s vizuálním vykreslováním odpovědí\n- **Živý monitor** — Stream všech požadavků procházejících proxy serverem v reálném čase\n\n<details>\n<summary><b>📈 15. „Potřebuji škálovat bez ztráty výkonu“</b></summary>\n</details>\n\nS rostoucím objemem požadavků generují stejné otázky bez ukládání do mezipaměti duplicitní náklady. Bez idempotence duplicitní požadavky plýtvají zpracováním. Je nutné dodržovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute řeší:**\n\n- **Sémantická mezipaměť** — Dvouvrstvá mezipaměť (signatura + sémantika) snižuje náklady a latenci\n- **Idempotence požadavku** — 5s deduplikační okno pro identické požadavky\n- **Detekce limitu rychlosti** – sledování otáček za minutu (RPM), minimální mezera a maximální souběžné sledování pro každého poskytovatele\n- **Upravitelné limity rychlosti** — Konfigurovatelné výchozí hodnoty v Nastavení → Odolnost s perzistencí\n- **Mezipaměť pro ověření klíčů API** — třívrstvá mezipaměť pro výkon produkčního prostředí\n- **Dashboard s telemetrií** – latence p50/p95/p99, statistiky mezipaměti, dostupnost\n\n<details>\n<summary><b>🤖 16. „Chci mít chování modelů globálně pod kontrolou“</b></summary>\n</details>\n\nVývojáři, kteří chtějí všechny odpovědi v určitém jazyce, se specifickým tónem nebo chtějí omezit tokeny pro uvažování. Konfigurace této funkce v každém nástroji/požadavku je nepraktická.\n\n**Jak to OmniRoute řeší:**\n\n- **Vložení systémového prompt** – Globální prompt aplikovaný na všechny požadavky\n- **Validace rozpočtu Thinking** — Řízení alokace tokenů na požadavek (průchozí, automatické, vlastní, adaptivní)\n- **6 strategií směrování** – Globální strategie, které určují, jak jsou požadavky distribuovány\n- **Směrovač se zástupnými znaky** — vzory `provider/*` dynamicky směrují k libovolnému poskytovateli\n- **Přepínání povolení/zakázání kombinací** – Přepínání kombinací přímo z řídicího panelu\n- **Přepínání poskytovatele** – Povolení/zakázání všech připojení pro poskytovatele jedním kliknutím\n- **Blokovaní poskytovatelé** – Vyloučení konkrétních poskytovatelů ze seznamu `/v1/models`\n\n<details>\n<summary><b>🧰 17. „Potřebuji nástroje MCP jako prvotřídní produktové funkce.“</b></summary>\n</details>\n\nMnoho bran umělé inteligence odhaluje MCP pouze jako skrytý implementační detail. Týmy potřebují viditelnou a spravovatelnou operační vrstvu.\n\n**Jak to OmniRoute řeší:**\n\n- MCP se zobrazuje v navigaci na řídicím panelu a na kartě protokolu koncového bodu.\n- Vyhrazená stránka pro správu MCP s procesy, nástroji, rozsahy a auditem\n- Vestavěný rychlý start pro `omniroute --mcp` a onboarding klienta\n\n<details>\n<summary><b>🧠 18. „Potřebuji orchestraci A2A se synchronizací a cestami úloh streamu.“</b></summary>\n</details>\n\nPracovní postupy agentů vyžadují jak přímé odpovědi, tak dlouhodobé streamované provádění s kontrolou životního cyklu.\n\n**Jak to OmniRoute řeší:**\n\n- Koncový bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamování SSE s šířením stavu terminálu\n- Rozhraní API životního cyklu úloh pro `tasks/get` a `tasks/cancel`\n\n<details>\n<summary><b>🛰️ 19. „Potřebuji skutečný stav procesu MCP, ne odhadovaný stav.“</b></summary>\n</details>\n\nProvozní týmy potřebují vědět, zda je MCP skutečně aktivní, nejen zda je API dosažitelné.\n\n**Jak to OmniRoute řeší:**\n\n- Soubor běhového heartbeatu s PID, časovými razítky, transportem, počtem nástrojů a režimem rozsahu\n- API stavu MCP kombinující prezenční signál a nedávnou aktivitu\n- Karty stavu uživatelského rozhraní pro zobrazení aktuálnosti procesů/provozuschopnosti/prezenčního signálu\n\n<details>\n<summary><b>📋 20. „Potřebuji auditovatelné provedení nástroje MCP“</b></summary>\n</details>\n\nKdyž nástroje mění konfiguraci nebo spouštějí operační akce, týmy potřebují forenzní sledovatelnost.\n\n**Jak to OmniRoute řeší:**\n\n- Protokolování auditu pro volání nástrojů MCP s podporou SQLite\n- Filtruje podle nástroje, úspěchu/neúspěchu, klíče API a stránkování\n- Tabulka auditu dashboardu + koncové body statistik pro automatizaci\n\n<details>\n<summary><b>🔐 21. „Potřebuji omezená oprávnění MCP pro každou integraci.“</b></summary>\n</details>\n\nRůzní klienti by měli mít přístup ke kategoriím nástrojů s nejnižšími oprávněními.\n\n**Jak to OmniRoute řeší:**\n\n- 9 detailních MCP sond pro kontrolovaný přístup k nástrojům\n- Vynucení rozsahu a viditelnost v uživatelském rozhraní správy MCP\n- Bezpečná výchozí poloha pro provozní nástroje\n\n<details>\n<summary><b>⚙️ 22. „Potřebuji provozní kontroly bez nutnosti přesouvání“</b></summary>\n</details>\n\nTýmy potřebují rychlé změny v běhovém prostředí během incidentů nebo nákladových událostí.\n\n**Jak to OmniRoute řeší:**\n\n- Přepněte aktivaci komba přímo z řídicího panelu MCP\n- Používejte profily odolnosti z předdefinovaných balíčků zásad\n- Resetujte stav jističe ze stejného ovládacího panelu\n\n<details>\n<summary><b>🔄 23. „Potřebuji živý přehled o životním cyklu úkolů A2A a jejich zrušení.“</b></summary>\n</details>\n\nBez přehledu o životním cyklu je obtížné třídit incidenty úkolů.\n\n**Jak to OmniRoute řeší:**\n\n- Výpis/filtrování úkolů podle státu/dovednosti s stránkováním\n- Podrobný přehled metadat úloh, událostí a artefaktů\n- Koncový bod zrušení úlohy a akce uživatelského rozhraní s potvrzením\n\n<details>\n<summary><b>🌊 24. „Potřebuji metriky aktivního streamu pro A2A zátěž“</b></summary>\n</details>\n\nStreamovací pracovní postupy vyžadují provozní přehled o souběžnosti a živých připojeních.\n\n**Jak to OmniRoute řeší:**\n\n- Čítače aktivních streamů integrované do stavu A2A\n- Časové razítko posledního úkolu a počty pro jednotlivé stavy\n- Karty A2A dashboardu pro monitorování provozu v reálném čase\n\n<details>\n<summary><b>🪪 25. „Potřebuji standardní vyhledávání agentů pro klienty“</b></summary>\n</details>\n\nExterní klienti a orchestratoři potřebují pro onboarding strojově čitelná metadata.\n\n**Jak to OmniRoute řeší:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazené v uživatelském rozhraní pro správu\n- API pro stav A2A zahrnuje metadata pro zjišťování pro automatizaci\n\n<details>\n<summary><b>🧭 26. „Potřebuji v uživatelském rozhraní produktu zjistitelnost protokolu.“</b></summary>\n</details>\n\nPokud uživatelé nemohou objevit protokolové povrchy, kvalita přijetí a podpory klesá.\n\n**Jak to OmniRoute řeší:**\n\n- Stránka Konsolidované **koncové body** s kartami pro koncové body Proxy, MCP, A2A a API\n- Přepínání stavu inline služby (Online/Offline) pro MCP a A2A\n- Odkazy z přehledu na vyhrazené karty pro správu\n\n<details>\n<summary><b>🧪 27. „Potřebuji komplexní ověření protokolu se skutečnými klienty.“</b></summary>\n</details>\n\nSimulované testy nestačí k ověření kompatibility protokolu před vydáním.\n\n**Jak to OmniRoute řeší:**\n\n- Sada E2E, která spouští aplikaci a používá skutečný transport klienta MCP SDK.\n- Klientské testy A2A pro toky zjišťování, odesílání, streamování, načítání a zrušení\n- Křížová kontrola tvrzení oproti API pro audit MCP a úkoly A2A\n\n<details>\n<summary><b>📡 28. „Potřebuji jednotnou pozorovatelnost napříč všemi rozhraními“</b></summary>\n</details>\n\nRozdělení pozorovatelnosti podle protokolu vytváří slepá místa a delší MTTR.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocené dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie požadavků napříč vrstvami OpenAI, MCP a A2A\n- Provozní API pro stav a automatizaci\n\n<details>\n<summary><b>💼 29. „Potřebuji jeden runtime pro proxy + nástroje + orchestraci agentů“</b></summary>\n</details>\n\nSpouštění mnoha samostatných služeb zvyšuje provozní náklady a počet poruch.\n\n**Jak to OmniRoute řeší:**\n\n- Proxy, MCP server a A2A server kompatibilní s OpenAI v jednom balíčku\n- Sdílené ověřování, odolnost, úložiště dat a pozorovatelnost\n- Konzistentní model politik napříč všemi interakčními plochami\n\n<details>\n<summary><b>🚀 30. „Potřebuji agentské pracovní postupy bez slepení kódu.“</b></summary>\n</details>\n\nTýmy ztrácejí rychlost při spojování více ad-hoc služeb a skriptů.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocená strategie koncových bodů pro klienty a agenty\n- Vestavěná uživatelská rozhraní pro správu protokolů a cesty pro ověřování kouře\n- Základy připravené pro produkční prostředí (zabezpečení, protokolování, odolnost, zálohování)\n\n### Příklady herních plánů (integrované případy užití)\n\n**Příručka A: Maximalizace placeného předplatného + levné zálohování**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Příručka B: Kódovací stack s nulovými náklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Příručka C: Nonstop záložní řetězec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Příručka D: Operace agentů s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Začněte zdarma — Nulové náklady na konfiguraci\n\n> Nastavte si kódování s umělou inteligencí během několika minut za **0 $/měsíc** . Propojte tyto bezplatné účty a využijte vestavěnou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelé odemčeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Připojení **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 – **neomezeně** |\n| 2 | Připojení k **iFlow** (Google OAuth) | kimi-k2-myšlení, qwen3-coder-plus, deepseek-r1... — **neomezeně** |\n| 3 | Připojení **Qwen** (kód zařízení) | qwen3-coder-plus, qwen3-coder-flash... — **neomezeně** |\n| 4 | Připojení **rozhraní příkazového řádku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180 000 GBP/měsíc zdarma** |\n| 5 | `/dashboard/combos` → Šablona **Free Stack (0 $)** | Automatické zařazení všech bezplatných poskytovatelů do routingu |\n\n**V libovolném IDE/CLI naveďte:** `http://localhost:20128/v1` · Klíč API: `any-string` · Hotovo.\n\n> **Volitelné doplňkové krytí (také zdarma):** Groq API klíč (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelů), Cerebras (1 milion tok/den).\n\n## ⚡ Rychlý start\n\n### 1) Nainstalujte a spusťte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uživatelé pnpm:** Po instalaci spusťte `pnpm approve-builds -g` , abyste povolili nativní skripty pro sestavení vyžadované programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard se otevírá na `http://localhost:20128` a základní URL API je `http://localhost:20128/v1` .\n\n| Příkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuštění serveru ( `PORT=20128` , API a dashboard na stejném portu) |\n| `omniroute --port 3000` | Nastavte kanonický/API port na 3000 |\n| `omniroute --mcp` | Spuštění MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevírat prohlížeč automaticky |\n| `omniroute --help` | Zobrazit nápovědu |\n\nVolitelný režim s rozděleným portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Připojte poskytovatele a vytvořte si klíč API\n\n1. Otevřete Dashboard → `Providers` a připojte alespoň jednoho poskytovatele (klíč OAuth nebo API).\n2. Otevřete Dashboard → `Endpoints` a vytvořte API klíč.\n3. (Volitelné) Otevřete Dashboard → `Combos` a nastavte záložní řetězec.\n\n### 3) Nasměrujte svůj kódovací nástroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilními s OpenAI.\n\n### 4) Povolení a ověření protokolů (v2.0)\n\n**MCP (pro operace řízené nástroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak připojte svého MCP klienta přes `stdio` a otestujte nástroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovní postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ověřte vše od začátku do konce (doporučeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ověřuje skutečné toky klientů MCP a A2A v porovnání se spuštěnou aplikací.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## 🐳 Docker\n\nOmniRoute je k dispozici jako veřejný obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlý běh:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostředí:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Používání Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | Štítek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovější stabilní verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuální verze |\n\n---\n\n## 🖥️ Desktopová aplikace – offline a vždy zapnutá\n\n> 🆕 **NOVINKA!** OmniRoute je nyní k dispozici jako **nativní desktopová aplikace** pro Windows, macOS a Linux.\n\nSpusťte OmniRoute jako samostatnou desktopovou aplikaci – pro lokální modely není potřeba žádný terminál, prohlížeč ani internet. Aplikace založená na platformě Electron obsahuje:\n\n- 🖥️ **Nativní okno** — Vyhrazené okno aplikace s integrací do systémové lišty\n- 🔄 **Automatické spuštění** — Spuštění OmniRoute po přihlášení do systému\n- 🔔 **Nativní oznámení** – Získejte upozornění na vyčerpání kvóty nebo problémy s poskytovateli\n- ⚡ **Instalace jedním kliknutím** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline režim** — Funguje plně offline s přiloženým serverem\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systémový zásobník\n\nPo minimalizaci se OmniRoute nachází v systémové liště a nabízí rychlé akce:\n\n- Otevřít řídicí panel\n- Změnit port serveru\n- Ukončit aplikaci\n\n📖 Úplná dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Přehled cen\n\n| Úroveň | Poskytovatel | Náklady | Obnovení kvóty | Nejlepší pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **💳 PŘEDPLATNÉ** | Claude Code (profesionál) | 20 dolarů měsíčně | 5 hodin + týdně | Již přihlášen/a k odběru |\n| Kodex (Plus/Pro) | 20–200 USD/měsíc | 5 hodin + týdně | Uživatelé OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisíc měsíčně + 1 tisíc denně | Každý! |\n| GitHub Copilot | 10–19 USD/měsíc | Měsíční | Uživatelé GitHubu |\n| **🔑 KLÍČ API** | NVIDIA NIM | **ZDARMA** (vývoj navždy) | ~40 ot./min | 70+ otevřených modelů |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší na světě |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisíc otáček za minutu | Ultrarychlá lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | Žádný | Nejlepší zdůvodnění ceny a kvality |\n| xAI Grok-4 Rychlý | **0,20/0,50 USD za 1 milion** 🆕 | Žádný | Nejrychlejší + volání nástroje, ultranízké |\n| xAI Grok-4 (standardní) | 0,20/1,50 USD za 1 milion 🆕 | Žádný | Vlajková loď Reasoning od xAI |\n| Mistral | Zkušební verze zdarma + placené | Omezená sazba | Evropská umělá inteligence |\n| OpenRouter | Platba za použití | Žádný | Více než 100 modelů agregováno. |\n| **💰 LEVNÉ** | GLM-5 (přes Z.AI) 🆕 | 0,5 USD/1 milion | Denně v 10:00 | Výstup 128 tisíc obrazových bodů, nejnovější vlajková loď |\n| GLM-4.7 | 0,6 USD/1 milion | Denně v 10:00 | Záloha rozpočtu |\n| MiniMax M2.5 🆕 | Vstup 0,3 USD/1 milion | 5hodinové válcování | Úvaha + agentní úkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinové válcování | Nejlevnější varianta |\n| Kimi K2.5 (Moonshot API) 🆕 | Platba za použití | Žádný | Přímý přístup k Moonshot API |\n| Kimi K2 | 9 dolarů měsíčně bez závazků | 10 milionů tokenů/měsíc | Předvídatelné náklady |\n| **🆓 ZDARMA** | iFlow | **0 dolarů** | Neomezený | 5 modelů neomezeně |\n| Qwen | **0 dolarů** | Neomezený | 4 modely neomezeně |\n| Kiro | **0 dolarů** | Neomezený | Claude Sonnet/Haiku (tvorce AWS) |\n\n> 🆕 **Přidány nové modely (březen 2026):** řada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkováno na 1143 ms – o 30 % rychlejší než Gemini 2.5 Flash), GLM-5 přes Z.AI s výstupem 128K, uvažování MiniMax M2.5, aktualizované ceny DeepSeek V3.2, Kimi K2.5 přes Moonshot Direct API.\n\n**💡 Kombinovaný balík za 0 $ — Kompletní bezplatná instalace:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\niFlow (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Nulové náklady. Nikdy nepřestávejte s kódováním.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a všechny záložní režimy se provede automaticky – žádné ruční přepínání.\n\n---\n\n---\n\n## 🆓 Bezplatné modely – Co skutečně získáte\n\n> Všechny níže uvedené modely jsou **100% zdarma a nevyžadují žádnou kreditní kartu** . OmniRoute mezi nimi automaticky propojí trasy, když dojde jedna kvóta – zkombinujte je všechny a získejte tak nerozlučnou kombinaci za 0 dolarů.\n\n### 🔵 CLAUDE MODELS (přes Kiro — AWS Builder ID)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-opus-4.6` | `kr/` | **Neomezený** | Nejnovější opus od Kira |\n\n### 🟢 MODELY IFLOW (Bezplatné OAuth — bez nutnosti platit kreditní kartou)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-plus` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `deepseek-r1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `minimax-m2.1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `kimi-k2` | `if/` | **Neomezený** | Žádný hlášený strop |\n\n### 🟡 MODELY QWEN (Ověření kódu zařízení)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-next` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `vision-model` | `qw/` | **Neomezený** | Multimodální (obrázky) |\n\n### 🟣 Rozhraní GEMINI CLI (Google OAuth)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisíc tok/měsíc** + 1 tisíc/den | Měsíční reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisíc měsíčně (sdílený bazén) | Vysoká kvalita |\n\n### ⚫ NVIDIA NIM (Bezplatný klíč API — build.nvidia.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vývojář) | Žádný limit tokenů | **~40 ot./min** | Více než 70 modelů; přechod na čisté limity sazeb v polovině roku 2025 |\n\nOblíbené bezplatné modely: `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`\n\n### ⚪ CEREBRAS (Bezplatný klíč API — inference.cerebras.ai)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenů/den** | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší inference LLM na světě; denně se resetuje |\n\nDostupné zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Bezplatný API klíč — console.groq.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisíc otáček za minutu** | 30 ot./min na model | Žádná kreditní karta; limit 429, neúčtováno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **💡 Ultimátní bezplatný zásobník:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> → iFlow (5 models, unlimited)\n> → Qwen (4 models, unlimited)\n> → Gemini CLI (180K/mo)\n> → Cerebras (1M tok/day)\n> → Groq (14.4K req/day)\n> → NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a už nikdy nebudete platit za umělou inteligenci.\n\n## 🎙️ Kombinovaná transkripce zdarma\n\n> Přepisujte libovolné audio/video za **0 $** – Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako záložní nástroj, Groq Whisper jako neomezená nouzová záloha.\n\n| Poskytovatel | Bezplatné kredity | Nejlepší model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| 🟢 **Deepgram** | **200 dolarů zdarma** (registrace) | `nova-3` — nejvyšší přesnost, více než 30 jazyků | Žádný limit RPM pro kredity zdarma |\n| 🔵 **AssemblyAI** | **50 dolarů zdarma** (registrace) | `universal-3-pro` — kapitoly, sentiment, osobní údaje | Žádný limit RPM pro kredity zdarma |\n| 🔴 **Groq** | **Navždy zdarma** | `whisper-large-v3` — OpenAI Šepot | 30 ot./min (omezená rychlost) |\n\n**Navrhovaná kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nPak v `/dashboard/media` → záložka **Přepis** : nahrajte libovolný zvukový nebo video soubor → vyberte kombinovaný koncový bod → získejte přepis v podporovaných formátech.\n\n## 💡 Klíčové vlastnosti\n\nOmniRoute v2.0 je navržen jako operační platforma, nikoli pouze jako proxy pro relé.\n\n### 🤖 Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dělá |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **MCP Server (16 nástrojů)** | Nástroje IDE/agent prostřednictvím 3 transportů: stdio, SSE ( `/api/mcp/sse` ), Streamovatelný HTTP ( `/api/mcp/stream` ) |\n| 🤝 **A2A server (JSON-RPC + SSE)** | Spouštění úloh mezi agenty se synchronizací a streamováním |\n| 🧭 **Konsolidovaná stránka koncových bodů** | Stránka pro správu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| 🎚️ **Přepínače pro povolení/zakázání služby** | Přepínače ZAP/VYP pro MCP a A2A s trvalým nastavením (výchozí: VYP) |\n| 🛰️ **Srdeční tep za běhu MCP** | Skutečný stav procesu (pid, doba provozuschopnosti, stáří heartbeatu, transport, režim rozsahu) |\n| 📋 **Auditní záznam MCP** | Filtrovatelné protokoly auditu s hodnocením úspěchu/neúspěchu a klíčovým přiřazením |\n| 🔐 **Vynucování rozsahu MCP** | 9 podrobných oprávnění pro řízený přístup k nástrojům |\n| 📡 **Správa životního cyklu úkolů A2A** | Seznam/filtrování úloh, kontrola událostí/artefaktů, zrušení spuštěných úloh |\n| 📋 **Objevení karty agenta** | `/.well-known/agent.json` pro automatické vyhledávání klientů |\n| 🧪 **Testovací postroj Protocol E2E** | Skutečné MCP SDK + toky klientů A2A v `test:protocols:e2e` |\n| ⚙️ **Provozní kontroly** | Kombinace přepínačů, použití profilů odolnosti, resetování jističů z jednoho ovládacího panelu |\n\n### 🧠 Směrování a inteligence\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| 🎯 **Inteligentní čtyřúrovňový záložní systém** | Automatická trasa: Předplatné → API klíč → Levné → Zdarma |\n| 📊 **Sledování kvót v reálném čase** | Počet tokenů v reálném čase + odpočet resetování pro každého poskytovatele |\n| 🔄 **Překlad formátu** | OpenAI ↔ Claude ↔ Gemini ↔ Odpovědi s konverzemi bezpečnými pro schéma |\n| 👥 **Podpora více účtů** | Více účtů na poskytovatele s inteligentním výběrem |\n| 🔄 **Automatická aktualizace tokenů** | Tokeny OAuth se automaticky obnovují při opakovaném pokusu. |\n| 🎨 **Vlastní kombinace** | 6 vyvažovacích strategií + řízení záložního řetězce |\n| 🌐 **Směrovač se zástupnými znaky** | dynamické směrování `provider/*` |\n| 🧠 **Přemýšlení o rozpočtových kontrolách** | Limity pro průchozí, automatické, vlastní a adaptivní uvažování |\n| 🔀 **Aliasy modelů** | Vestavěné + vlastní aliasování modelů a bezpečnost migrace |\n| ⚡ **Degradace pozadí** | Směrujte úlohy na pozadí s nízkou prioritou na levnější modely |\n| 🧪 **Chytré směrování s ohledem na úkoly** | Automatický výběr modelu podle typu obsahu (kódování/vize/analýza/sumarizace) |\n| 💬 **Vstřikování do systému** | Globální kontroly chování uplatňované konzistentně |\n| 📄 **Kompatibilita API pro odpovědi** | Plná podpora `/v1/responses` pro Codex a pokročilé agentické pracovní postupy |\n\n### 🎵 Multimodální API\n\n| Funkce | Co to dělá |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Generování obrázků** | `/v1/images/generations` s cloudovým a lokálním backendem |\n| 📐 **Vložení** | `/v1/embeddings` pro vyhledávání a RAG pipelines |\n| 🎤 **Přepis zvuku** | `/v1/audio/transcriptions` (Whisper a další poskytovatelé) |\n| 🔊 **Převod textu na řeč** | `/v1/audio/speech` (více enginů/poskytovatelů) |\n| 🎬 **Generování videa** | `/v1/videos/generations` (pracovní postupy ComfyUI + SD WebUI) |\n| 🎵 **Hudební generace** | `/v1/music/generations` (pracovní postupy ComfyUI) |\n| 🛡️ **Moderování** | Bezpečnostní kontroly `/v1/moderations` |\n| 🔀 **Změna pořadí** | `/v1/rerank` pro hodnocení relevance |\n| 🔍 **Vyhledávání na webu** 🆕 | `/v1/search` — 5 poskytovatelů (Serper, Brave, Perplexity, Exa, Tavily), více než 6 500 zdarma/měsíc, automatické přepnutí na záložní systém, mezipaměť |\n\n### 🛡️ Odolnost, bezpečnost a správa věcí veřejných\n\n| Funkce | Co to dělá |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| 🔌 **Jističe** | Vypnutí/obnovení pro každý model s ovládáním prahových hodnot |\n| 🎯 **Modely s ohledem na koncové body** | Vlastní modely deklarují podporované koncové body + formát API |\n| 🛡️ **Stádo proti hromům** | Ochrana mutexu a semaforu při událostech opakování/rychlosti |\n| 🧠 **Sémantická + podpisová mezipaměť** | Snížení nákladů/latence díky dvěma vrstvám mezipaměti |\n| ⚡ **Žádost o idempotenci** | Okno ochrany proti duplikacím |\n| 🔒 **Falšování otisků prstů pomocí TLS** | Otisk TLS podobný prohlížeči – **snižuje detekci botů a nahlašování účtů** |\n| 🔏 **Porovnávání otisků prstů v CLI** | Shoduje se s nativními podpisy požadavků CLI – **snižuje riziko zablokování a zároveň zachovává IP adresu proxy** |\n| 🌐 **Filtrování IP adres** | Ovládání seznamu povolených/blokovaných položek pro odhalená nasazení |\n| 📊 **Upravitelné limity rychlosti** | Konfigurovatelné globální/na úrovni poskytovatele limity s perzistencí |\n| 🔑 **Správa klíčů API a stanovení rozsahu** | Bezpečné vydávání/rotace klíčů a kontroly modelu/poskytovatele |\n| 🛡️ **Chráněné `/models`** | Volitelné ověřování a skrytí poskytovatele pro katalog modelů |\n\n### 📊 Pozorovatelnost a analytika\n\n| Funkce | Co to dělá |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| 📝 **Žádost + protokolování proxy** | Úplné protokolování požadavků/odpovědí a proxy |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Sjednocený panel protokolů** | Zobrazení požadavků, proxy, auditu a konzole na jedné stránce |\n| 🔍 **Vyžádat si telemetrii** | Latence p50/p95/p99 a trasování požadavků |\n| 🏥 **Panel zdraví** | Doba provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti |\n| 💰 **Sledování nákladů** | Kontrola rozpočtu a přehled o cenách pro jednotlivé modely |\n| 📈 **Analytické vizualizace** | Přehledy využití modelů/poskytovatelů a zobrazení trendů |\n| 🧪 **Rámec hodnocení** | Testování zlaté sady s konfigurovatelnými strategiemi shody |\n\n### ☁️ Nasazení a platforma\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| 🌐 **Nasazení kdekoli** | Localhost, VPS, Docker, cloudová prostředí |\n| 💾 **Synchronizace s cloudem** | Synchronizace konfigurace přes cloud worker |\n| 🔄 **Zálohování/Obnovení** | Toky exportu/importu a obnovy po havárii |\n| 🧙 **Průvodce nástupem** | Průvodce prvním spuštěním |\n| 🔧 **Panel nástrojů CLI** | Nastavení oblíbených kódovacích nástrojů jedním kliknutím |\n| 🎮 **Modelové hřiště** | Otestujte libovolného poskytovatele/model/koncový bod z řídicího panelu |\n| 🔏 **Přepínač otisků prstů v příkazovém řádku** | Porovnávání otisků prstů podle poskytovatele v Nastavení &gt; Zabezpečení |\n| 🌐 **i18n (30 jazyků)** | Plná jazyková podpora dashboardu a dokumentace s psaním zprava doleva |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Adresář vlastních dat** | Přepsání `DATA_DIR` pro umístění úložiště |\n\n### Hluboký pohled na funkce\n\n#### Chytrá záložní funkce s praktickou kontrolou nákladů\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyž selže kvóta, rychlost nebo stav, OmniRoute automaticky přejde k dalšímu kandidátovi bez nutnosti ručního přepínání.\n\n#### Správa protokolů, která je viditelná a ovladatelná\n\n- MCP + A2A jsou viditelné v uživatelském rozhraní a dokumentaci (nejsou skryté)\n- API pro stav protokolu zpřístupňují živá provozní data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnují akce pro operace 2. dne (přepínání kombinací, resetování jističů, zrušení úkolů)\n\n#### Pracovní postup překladatele + validace\n\nOblast překladatele zahrnuje:\n\n- **Hřiště** : kontroly transformace požadavků\n- **Tester chatu** : kompletní okružní cesta požadavku/odpovědi\n- **Testovací stolice** : více případů v jednom běhu\n- **Živý monitor** : zobrazení provozu v reálném čase\n\nPlus validace protokolu se skutečnými klienty pomocí `npm run test:protocols:e2e` .\n\n> 📖 **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** — Referenční informace o nástrojích, konfigurace IDE a příklady klientů\n>\n> 📖 **[Soubor README pro A2A Server](src/lib/a2a/README.md)** — Dovednosti, metody JSON-RPC, streamování a životní cyklus úloh\n\n## 🧪 Hodnocení (Evals)\n\nOmniRoute obsahuje vestavěný hodnotící rámec pro testování kvality odpovědí LLM v porovnání se zlatou sadou. Přístup k němu je možný přes **Analýzy → Hodnocení** v dashboardu.\n\n### Vestavěná zlatá sada\n\nPředinstalovaná sada „OmniRoute Golden Set“ obsahuje testovací případy pro:\n\n- Zdravím, matematika, zeměpis, generování kódu\n- Shoda s formátem JSON, překlad, generování markdownů\n- Bezpečnostní odmítnutí (škodlivý obsah), počítání, booleovská logika\n\n### Strategie hodnocení\n\n| Strategie | Popis | Příklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Výstup se musí přesně shodovat | `\"4\"` |\n| `contains` | Výstup musí obsahovat podřetězec (bez rozlišení velkých a malých písmen) | `\"Paris\"` |\n| `regex` | Výstup musí odpovídat vzoru regulárních výrazů | `\"1.*2.*3\"` |\n| `custom` | Vlastní JS funkce vrací true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Průvodce nastavením\n\n### Nastavení protokolu (MCP + A2A)\n\n<details>\n<summary><b>🧩 Nastavení MCP (Model Context Protocol)</b></summary>\n</details>\n\nSpuštění MCP transportu v režimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporučený postup ověření:\n\n1. Připojte svého MCP klienta přes stdio.\n2. Spusťte `omniroute_get_health` .\n3. Spusťte `omniroute_list_combos` .\n4. Otevřete `/dashboard/mcp` pro ověření prezenčního signálu, aktivity a auditu.\n\nUžitečná API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n<details>\n<summary><b>🤝 Nastavení A2A (Agent2Agent)</b></summary>\n</details>\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat úkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSpráva životního cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvozní uživatelské rozhraní:\n\n- `/dashboard/a2a` pro pozorovatelnost úloh/stavů/streamů a akce kouření\n\n<details>\n<summary><b>🧪 Komplexní validace protokolu</b></summary>\n</details>\n\nOvěřte oba protokoly se skutečnými klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTím se ověřuje:\n\n- Připojení/seznam/volání klienta MCP SDK\n- A2A objevování/odesílání/streamování/získávání/zrušení\n- Křížová kontrola dat v auditu MCP a API pro správu úloh A2A\n\n<details>\n<summary><b>💳 Poskytovatelé předplatného</b></summary>\n</details>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionály:** Pro složité úkoly používejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvótu pro každý model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Správa limitů účtu Codex (5h + týdně)\n\nKaždý účet Codex má nyní přepínače zásad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinového prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zásadu týdenního prahu okna.\n- Prahové chování: když povolené okno dosáhne využití &gt;=90 %, je daný účet přeskočen.\n- Chování rotace: OmniRoute automaticky přesměruje na další způsobilý účet Codex.\n- Chování při resetování: Po `resetAt` určité doby se účet automaticky opět stane způsobilým.\n\nScénáře:\n\n- `5h ON` + `Weekly ON` : účet je přeskočen, když kterékoli z oken dosáhne prahové hodnoty.\n- `5h OFF` + `Weekly ON` : účet může být zablokován pouze týdenním používáním.\n- `5h ON` + `Weekly OFF` : účet může být zablokován pouze při 5hodinovém používání.\n- `resetAt` passed: účet se automaticky znovu zapne (bez ručního opětovného povolení).\n\n### Gemini CLI (ZDARMA 180 000/měsíc!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepší hodnota:** Obrovská bezplatná úroveň! Použijte ji před placenými úrovněmi.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n<details>\n<summary><b>🔑 Poskytovatelé klíčů API</b></summary>\n</details>\n\n### NVIDIA NIM (BEZPLATNÝ přístup pro vývojáře — více než 70 modelů)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Získejte zdarma klíč API (včetně 1000 inferenčních kreditů)\n3. Ovládací panel → Přidat poskytovatele → NVIDIA NIM:\n - Klíč API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a více než 50 dalších\n\n**Tip pro profesionály:** API kompatibilní s OpenAI – funguje bez problémů s překladem formátů OmniRoute!\n\n### Hluboké vyhledávání\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatná úroveň!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Získejte klíč API (včetně bezplatné úrovně)\n3. Ovládací panel → Přidat poskytovatele → Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionály:** Ultrarychlá inference – nejlepší pro kódování v reálném čase!\n\n### OpenRouter (100+ modelů)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → OpenRouter\n\n**Modely:** Získejte přístup k více než 100 modelům od všech hlavních poskytovatelů prostřednictvím jediného klíče API.\n\n<details>\n<summary><b>💰 Levní poskytovatelé (záložní)</b></summary>\n</details>\n\n### GLM-4.7 (Denní reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Získejte klíč API z kódovacího plánu\n3. Nástěnka → Přidat klíč API:\n - Poskytovatel: `glm`\n - Klíč API: `your-key`\n\n**Použití:** `glm/glm-4.7`\n\n**Tip pro profesionály:** Programovací plán nabízí 3× kvótu za cenu 1/7! Obnovuje se denně v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionály:** Nejlevnější varianta pro dlouhý kontext (1 milion tokenů)!\n\n### Kimi K2 (paušální poplatek 9 dolarů měsíčně)\n\n1. Odebírat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `kimi/kimi-latest`\n\n**Tip pro profesionály:** Fixních 9 $/měsíc za 10 milionů tokenů = efektivní náklady 0,90 $/1 milion!\n\n<details>\n<summary><b>🆓 BEZPLATNÍ poskytovatelé (nouzové zálohování)</b></summary>\n</details>\n\n### iFlow (5 BEZPLATNÝCH modelů přes OAuth)\n\n```bash\nDashboard → Connect iFlow\n→ iFlow OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kódem zařízení)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n<details>\n<summary><b>🎨 Vytvořte kombinace</b></summary>\n</details>\n\n### Příklad 1: Maximalizace předplatného → Levné zálohování\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Příklad 2: Pouze zdarma (nulové náklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n<details>\n<summary><b>🔧 Integrace s rozhraním příkazového řádku</b></summary>\n</details>\n\n### IDE kurzoru\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jedním kliknutím použijte stránku **Nástroje CLI** na řídicím panelu nebo ručně upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Možnost 1 – Dashboard (doporučeno):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Možnost 2 – Manuální úprava:** Úprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznámka:** OpenClaw funguje pouze s lokálním OmniRoute. Místo `localhost` použijte `127.0.0.1` , abyste se vyhnuli problémům s rozlišením IPv6.\n\n### Cline / Pokračovat / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Přidání OmniRoute jako vlastního poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvořte/upravte `opencode.json` v kořenovém adresáři projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` přidejte jakýkoli model dostupný ve vašem koncovém bodu OmniRoute `/v1/models` . Použijte formát `provider/model-id` z vašeho dashboardu OmniRoute.\n\n---\n\n## 🐛 Řešení problémů\n\n<details>\n<summary><b>Kliknutím rozbalíte průvodce řešením problémů</b></summary>\n</details>\n\n**\"Jazykový model neposkytoval zprávy\"**\n\n- Kvóta poskytovatele vyčerpána → Zkontrolujte sledování kvót na řídicím panelu\n- Řešení: Použijte záložní kombinovanou variantu nebo přejděte na levnější úroveň\n\n**Omezení rychlosti**\n\n- Kvóta předplatného vyčerpána → Přechod na GLM/MiniMax\n- Přidat kombo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vypršela**\n\n- Automaticky aktualizováno službou OmniRoute\n- Pokud problémy přetrvávají: Ovládací panel → Poskytovatel → Znovu připojit\n\n**Vysoké náklady**\n\n- Zkontrolujte statistiky využití v sekci Nástěnka → Náklady\n- Přepnout primární model na GLM/MiniMax\n- Pro nekritické úlohy použijte bezplatnou úroveň (Gemini CLI, iFlow).\n\n**Porty řídicího panelu/API jsou nesprávné**\n\n- `PORT` je kanonický základní port (a standardně port API)\n- `API_PORT` přepisuje pouze posluchač API kompatibilní s OpenAI.\n- `DASHBOARD_PORT` přepisuje pouze posluchač dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaši veřejnou URL adresu řídicího panelu (pro zpětná volání OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ověřte, zda `BASE_URL` odkazuje na vaši spuštěnou instanci.\n- Ověřte, zda `CLOUD_URL` odkazuje na váš očekávaný cloudový koncový bod.\n- Udržujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na straně serveru.\n\n**První přihlášení nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud není nastaveno, záložní heslo je `123456`\n\n**Žádné protokoly požadavků**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test připojení ukazuje „Neplatné“ pro poskytovatele kompatibilní s OpenAI**\n\n- Mnoho poskytovatelů nezpřístupňuje koncový bod `/models`\n- OmniRoute v1.0.6+ zahrnuje záložní ověření pomocí dokončení chatu\n- Zajistěte, aby základní URL adresa obsahovala příponu `/v1`\n\n### 🔐 OAuth na vzdáleném serveru\n\n<a name=\"oauth-on-a-remote-server\"></a>\n\n> **⚠️ Důležité pro uživatele, kteří provozují OmniRoute na VPS, Dockeru nebo jakémkoli vzdáleném serveru**\n\n#### Proč selhává OAuth v rozhraní CLI Antigravity / Gemini na vzdálených serverech?\n\nPoskytovatelé rozhraní CLI **Antigravity** a **Gemini** používají **Google OAuth 2.0** . Google vyžaduje, aby se `redirect_uri` v toku OAuth přesně shodoval s jedním z předregistrovaných URI v konzoli Google Cloud Console aplikace.\n\nPřihlašovací údaje OAuth, které jsou součástí OmniRoute, jsou registrovány **pouze pro `localhost`** . Když přistupujete k OmniRoute na vzdáleném serveru (např. `https://omniroute.myserver.com` ), Google odmítne ověření pomocí:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Řešení: Nakonfigurujte si vlastní přihlašovací údaje OAuth\n\nV Google Cloud Console je potřeba vytvořit **ID klienta OAuth 2.0** s URI vašeho serveru.\n\n#### Krok za krokem\n\n**1. Otevřete konzoli Google Cloud**\n\nPřejděte na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvořte nové ID klienta OAuth 2.0**\n\n- Klikněte na **„+ Vytvořit přihlašovací údaje“** → **„ID klienta OAuth“**\n- Typ aplikace: **„Webová aplikace“**\n- Název: cokoli chcete (např. `OmniRoute Remote` )\n\n**3. Přidejte autorizované URI pro přesměrování**\n\nDo pole **„Autorizované identifikátory URI pro přesměrování“** přidejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraďte `your-server.com` doménou nebo IP adresou vašeho serveru (v případě potřeby uveďte i port, např. `http://45.33.32.156:20128/callback` ).\n\n**4. Uložte a zkopírujte přihlašovací údaje**\n\nPo vytvoření Google zobrazí **ID klienta** a **tajný kód klienta** .\n\n**5. Nastavení proměnných prostředí**\n\nVe vašem souboru `.env` (nebo proměnných prostředí Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu připojit**\n\nŘídicí panel → Poskytovatelé → Antigravity (nebo Gemini CLI) → OAuth\n\nGoogle nyní bude správně přesměrovávat na `https://your-server.com/callback` .\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nPokud si teď nechcete nastavovat vlastní přihlašovací údaje, můžete stále použít **ruční postup pro URL** :\n\n1. OmniRoute otevírá autorizační URL od Googlu\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru).\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče (i když se stránka nenačte)\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute.\n5. Klikněte na **„Připojit“**\n\n> To funguje, protože autorizační kód v URL adrese je platný bez ohledu na to, zda se načetla přesměrovací stránka.\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nChcete-li získat přístup k přihlašovacím údajům bez vlastní konfigurace, můžete použít následující postup:\n\n1. OmniRoute otevře URL autorizace Google\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru)\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute\n5. Klikněte na **„Připojit\"**\n\n> Toto řešení funguje, protože autorizační kód v URL adrese je platný bez ohledu na načtení přesměrovací stránky.\n\n---\n\n## 🛠️ Technologický stack\n\n<details>\n<summary><b>Kliknutím rozbalíte podrobnosti o technologickém stacku</b></summary>\n</details>\n\n- **Runtime** : Node.js 18–22 LTS (⚠️ Node.js 24+ **není podporován** — nativní binární soubory `better-sqlite3` jsou nekompatibilní)\n- **Jazyk** : TypeScript 5.9 — **100% TypeScript** napříč `src/` a `open-sse/` ( `any` v základních modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databáze** : LowDB (JSON) + SQLite (stav domény + protokoly proxy + audit MCP + rozhodnutí o směrování)\n- **Schémata** : Zod (validace I/O nástrojů MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamování** : Události odeslané serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klíče + autorizace s rozsahem MCP\n- **Testování** : Node.js test runner + Vitest (900+ testů včetně unit, integračních, E2E)\n- **CI/CD** : Akce GitHubu (automatické publikování v npm + Docker Hub při vydání)\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **Balíček** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistič, exponenciální odstavení, ochrana proti hromům, falešné TLS, automatické kombinované samoopravování\n\n---\n\n## 📖 Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uživatelská příručka](docs/USER_GUIDE.md) | Poskytovatelé, kombinace, integrace CLI, nasazení |\n| [Referenční informace k API](docs/API_REFERENCE.md) | Všechny koncové body s příklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nástrojů MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamování, správa úloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorové bodování, balíčky režimů, samoléčba |\n| [Odstraňování problémů](docs/TROUBLESHOOTING.md) | Běžné problémy a jejich řešení |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a interní prvky systému |\n| [Přispívání](CONTRIBUTING.md) | Nastavení a pokyny pro vývoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpečnostní zásady](SECURITY.md) | Hlášení zranitelností a bezpečnostní postupy |\n| [Nasazení virtuálního počítače](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletní průvodce: Nastavení virtuálního počítače + nginx + Cloudflare |\n| [Galerie funkcí](docs/FEATURES.md) | Vizuální prohlídka řídicího panelu se snímky obrazovky |\n| [Kontrolní seznam vydání](docs/RELEASE_CHECKLIST.md) | Kroky ověření před vydáním |\n\n---\n\n## 🗺️ Plán\n\nOmniRoute má **v plánu více než 210 funkcí** v několika fázích vývoje. Zde jsou klíčové oblasti:\n\n| Kategorie | Plánované funkce | Hlavní body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| 🧠 **Směrování a inteligence** | 25+ | Směrování s nejnižší latencí, směrování založené na tagech, kontrola kvót před výstupem, výběr účtu P2C |\n| 🔒 **Zabezpečení a dodržování předpisů** | 20+ | Zpevnění SSRF, maskování přihlašovacích údajů, limit rychlosti pro každý koncový bod, stanovení rozsahu klíčů pro správu |\n| 📊 **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledování kvót v reálném čase, sledování nákladů podle modelu |\n| 🔄 **Integrace poskytovatelů** | 20+ | Dynamický registr modelů, doba zchlazení poskytovatelů, Codex pro více účtů, analýza kvót Copilota |\n| ⚡ **Výkon** | 15+ | Dvojitá vrstva mezipaměti, mezipaměť výzev, mezipaměť odpovědí, udržování streamování, dávkové API |\n| 🌐 **Ekosystém** | 10+ | WebSocket API, horké opětovné načítání konfigurace, distribuované úložiště konfigurace, komerční režim |\n\n### 🔜 Již brzy\n\n- 🔗 **Integrace OpenCode** — Nativní podpora poskytovatelů pro IDE kódování s AI v OpenCode\n- 🔗 **Integrace TRAE** — Plná podpora vývojového rámce TRAE pro umělou inteligenci\n- 📦 **Dávkové API** — Asynchronní dávkové zpracování hromadných požadavků\n- 🎯 **Směrování na základě tagů** — Směrování požadavků na základě vlastních tagů a metadat\n- 💰 **Strategie nejnižších nákladů** – Automaticky vybere nejlevnějšího dostupného poskytovatele\n\n> 📝 Úplné specifikace funkcí jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobných specifikací)\n\n---\n\n## 👥 Přispěvatelé\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Přispěvatelé](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak přispět\n\n1. Vytvoření forku repozitáře\n2. Vytvořte si vlastní větev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrďte změny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do větve ( `git push origin feature/amazing-feature` )\n5. Otevřít žádost o změny (pull request)\n\nPodrobné pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydání nové verze\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Hvězdná historie\n\n## Hvězdáři v průběhu času\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvězdáři v průběhu času](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## 🙏 Poděkování\n\nZvláštní poděkování patří **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** – původnímu projektu, který inspiroval tento fork. OmniRoute staví na tomto neuvěřitelném základu s dalšími funkcemi, multimodálními API a kompletním přepsáním TypeScriptu.\n\nZvláštní poděkování patří **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – původní implementaci Go, která inspirovala tento JavaScriptový port.\n\n---\n\n## 📄 Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n<div align=\"center\">\n <sub>Vytvořeno s ❤️ pro vývojáře, kteří programují 24 hodin denně, 7 dní v týdnu</sub>\n <br>\n <sub><p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\">omniroute.online</a></p></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "a5393a3ec4e717f2ef97fe4f66f3bc836c996ba2": {"t": 1785764460.8202274, "n": 92285, "h": "62d8b22a2a894095", "c": "# 🚀 OmniRoute — Bezplatná brána umělé inteligence\n\n### Nikdy nepřestávejte s kódováním. Chytré směrování k **BEZPLATNÝM a levným modelům AI** s automatickým přepínáním mezi záložními systémy.\n\n_Váš univerzální API proxy – jeden endpoint, více než 44 poskytovatelů, nulové výpadky. Nyní s orchestrací agentů **MCP a A2A** ._\n\n**Dokončení chatu • Vkládání • Generování obrázků • Video • Hudba • Audio • Změna pořadí • **Vyhledávání na webu** • MCP server • A2A protokol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n</div>\n<p data-md-type=\"paragraph\"><a href=\"https://www.npmjs.com/package/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/npm/v/omniroute?color=cb3837&amp;logo=npm\" alt=\"verze npm\" data-md-type=\"image\"><a href=\"https://hub.docker.com/r/diegosouzapw/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&amp;logo=docker&amp;color=2496ED\" alt=\"Docker Hub\" data-md-type=\"image\"><a href=\"https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/github/license/diegosouzapw/OmniRoute\" alt=\"Licence\" data-md-type=\"image\"><a href=\"https://omniroute.online\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&amp;logoColor=white\" alt=\"Webové stránky\" data-md-type=\"image\"><a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&amp;logoColor=white\" alt=\"WhatsApp\" data-md-type=\"image\"></p>\n<p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\" data-md-type=\"link\">🌐 Webové stránky</a> • <a href=\"#-quick-start\" data-md-type=\"link\">🚀 Rychlý start</a> • <a href=\"#-key-features\" data-md-type=\"link\">💡 Funkce</a> • <a href=\"#-documentation\" data-md-type=\"link\">📖 Dokumentace</a> • <a href=\"#-pricing-at-a-glance\" data-md-type=\"link\">💰 Ceník</a> • <a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\">💬 WhatsApp</a></p>\n<div data-md-type=\"block_html\"></div>\n\n🌐 **Dostupné v:** 🇺🇸 [Angličtina](README.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [maďarština](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonésie](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nizozemsko](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)\n\n---\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n## 🖼️ Hlavní ovládací panel\n\n<div align=\"center\"> <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"Řídicí panel OmniRoute\" width=\"800\"> </div>\n\n---\n\n## 📸 Náhled řídicího panelu\n\n<details>\n<summary><b>Kliknutím zobrazíte snímky obrazovky z řídicího panelu</b></summary>\n</details>\n\n| Strana | Snímek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelé** | ![Poskytovatelé](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdraví** | ![Zdraví](docs/screenshots/04-health.png) |\n| **Překladatel** | ![Překladatel](docs/screenshots/05-translator.png) |\n| **Nastavení** | ![Nastavení](docs/screenshots/06-settings.png) |\n| **Nástroje CLI** | ![Nástroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly používání** | ![Používání](docs/screenshots/08-usage.png) |\n| **Koncové body** | ![Koncové body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### 🤖 Bezplatný poskytovatel umělé inteligence pro vaše oblíbené programátory\n\n_Připojte libovolný nástroj IDE nebo CLI s umělou inteligencí přes OmniRoute — bezplatnou API bránu pro neomezené kódování._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openclaw/openclaw\"><img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"><br><b>OpenClaw</b></a><br> <sub>⭐ 205 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/HKUDS/nanobot\"><img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"><br><b>NanoBot</b></a><br> <sub>⭐ 20,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/sipeed/picoclaw\"><img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"><br><b>PicoClaw</b></a><br> <sub>⭐ 14,6 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/zeroclaw-labs/zeroclaw\"><img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"><br><b>ZeroClaw</b></a><br> <sub>⭐ 9,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/nearai/ironclaw\"><img src=\"./public/providers/ironclaw.png\" alt=\"Železný dráp\" width=\"48\"><br><b>Železný dráp</b></a><br> <sub>⭐ 2,1 tisíce</sub> </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anomalyco/opencode\"><img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"><br><b>OpenCode</b></a><br> <sub>⭐ 106 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openai/codex\"><img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"><br><b>Codex CLI</b></a><br> <sub>⭐ 60,8 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anthropics/claude-code\"><img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"><br><b>Claude Code</b></a><br> <sub>⭐ 67,3 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/google-gemini/gemini-cli\"><img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"><br> <b>Gemini CLI</b></a><br> <sub>⭐ 94,7 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/Kilo-Org/kilocode\"><img src=\"./public/providers/kilocode.png\" alt=\"Kilo kód\" width=\"48\"><br><b>Kilo kód</b></a><br> <sub>⭐ 15,5 tisíc</sub> </td>\n </tr>\n </table>\n\n<sub>📡 Všichni agenti se připojují přes <code>http://localhost:20128/v1</code> nebo <code>http://cloud.omniroute.online/v1</code> — jedna konfigurace, neomezené modely a kvóty</sub>\n\n---\n\n## 🤔 Proč OmniRoute?\n\n**Přestaňte plýtvat penězi a narážet na limity:**\n\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Kvóta předplatného vyprší každý měsíc\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Limity rychlosti vám zabrání v kódování\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Drahá API (20–50 USD/měsíc na poskytovatele)\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Ruční přepínání mezi poskytovateli\n\n**OmniRoute to řeší:**\n\n- ✅ **Maximalizujte předplatné** – Sledujte kvótu, využijte každou částku před resetováním\n- ✅ **Automatické záložní** – Předplatné → API klíč → Levné → Zdarma, žádné výpadky\n- ✅ **Více účtů** – Round-robin mezi účty u jednotlivých poskytovatelů\n- ✅ **Univerzální** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakýmkoli nástrojem CLI\n\n---\n\n## 📧 Podpora\n\n> 💬 **Přidejte se k naší komunitě!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získejte pomoc, sdílejte tipy a buďte v obraze.\n\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problémy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitní skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Přispívání** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevřete žádost o příspěvek nebo si vyberte `good first issue`\n- **Původní projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### 🐛 Hlásíte chybu?\n\nPři otevírání problému spusťte příkaz system-info a přiložte vygenerovaný soubor:\n\n```bash\nnpm run system-info\n```\n\nTím se vygeneruje soubor `system-info.txt` s verzí Node.js, verzí OmniRoute, podrobnostmi o operačním systému, nainstalovanými nástroji CLI (qoder, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systémovými balíčky – vše, co potřebujeme k rychlé reprodukci vašeho problému. Soubor přiložte přímo k vašemu problému na GitHubu.\n\n---\n\n## 🔄 Jak to funguje\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 Co řeší OmniRoute — 30 skutečných problémů a případů použití\n\n> **Každý vývojář používající nástroje umělé inteligence se s těmito problémy setkává denně.** OmniRoute byl vytvořen tak, aby je všechny vyřešil – od překročení nákladů po regionální bloky, od nefunkčních toků OAuth až po operace s protokoly a sledovatelnost v podniku.\n\n<details>\n<summary><b>💸 1. „Platím si drahé předplatné, ale stále mě ruší limity“</b></summary>\n</details>\n\nVývojáři platí za Claude Pro, Codex Pro nebo GitHub Copilot 20–200 dolarů měsíčně. I při platbě má kvóta strop – 5 hodin používání, týdenní limity nebo limity rychlosti za minutu. Uprostřed kódovací relace poskytovatel přestane reagovat a vývojář ztrácí plynulost a produktivitu.\n\n**Jak to OmniRoute řeší:**\n\n- **Inteligentní čtyřúrovňová záložní služba** – Pokud dojde kvóta předplatného, ​​automaticky se přesměruje na API klíč → Levné → Zdarma bez manuálního zásahu\n- **Sledování kvót v reálném čase** – Zobrazuje spotřebu tokenů v reálném čase s odpočítáváním resetování (5 hodin, denně, týdně)\n- **Podpora více účtů** – Více účtů u jednoho poskytovatele s automatickým přepínáním – když jeden dojde, přepne se na další\n- **Vlastní kombinace** — Přizpůsobitelné záložní řetězce se 6 strategiemi vyvažování (fill-first, round robin, P2C, náhodné, nejméně používané, nákladově optimalizované)\n- **Codex Business Quotas** — Sledování kvót pracovního prostoru firmy/týmu přímo v dashboardu\n\n<details>\n<summary><b>🔌 2. „Potřebuji použít více poskytovatelů, ale každý má jiné API“</b></summary>\n</details>\n\nOpenAI používá jeden formát, Claude (Anthropic) jiný a Gemini ještě třetí. Pokud chce vývojář testovat modely od různých poskytovatelů nebo mezi nimi přecházet, musí překonfigurovat SDK, změnit koncové body a vypořádat se s nekompatibilními formáty. Vlastní poskytovatelé (FriendLI, NIM) mají nestandardní koncové body modelů.\n\n**Jak to OmniRoute řeší:**\n\n- **Sjednocený koncový bod** — Jeden `http://localhost:20128/v1` slouží jako proxy pro všech 67+ poskytovatelů.\n- **Překlad formátu** — Automatický a transparentní: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Sanitizace odpovědí** — Odstraňuje nestandardní pole ( `x_groq` , `usage_breakdown` , `service_tier` ), která porušují OpenAI SDK v1.83+\n- **Normalizace rolí** — Převádí `developer` → `system` pro poskytovatele bez OpenAI; `system` → `user` pro GLM/ERNIE\n- **Extrakce tagů Think** — Extrahuje bloky `<think>` z modelů, jako je DeepSeek R1, do standardizovaného `reasoning_content`\n- **Strukturovaný výstup pro Gemini** — `json_schema` → automatická konverze `responseMimeType` / `responseSchema`\n- **Výchozí hodnota `stream` je `false`** – Odpovídá specifikaci OpenAI, čímž se zabrání neočekávanému SSE v Python/Rust/Go SDK.\n\n<details>\n<summary><b>🌐 3. „Můj poskytovatel AI blokuje můj region/zemi“</b></summary>\n</details>\n\nPoskytovatelé jako OpenAI/Codex blokují přístup z určitých geografických oblastí. Uživatelé se během připojení OAuth a API dostávají k chybám jako `unsupported_country_region_territory` . To je obzvláště frustrující pro vývojáře z rozvojových zemí.\n\n**Jak to OmniRoute řeší:**\n\n- **3úrovňová konfigurace proxy** – Konfigurovatelná proxy na 3 úrovních: globální (veškerý provoz), pro jednotlivé poskytovatele (pouze jeden poskytovatel) a pro jednotlivé připojení/klíč\n- **Barevně kódované odznaky proxy** – Vizuální indikátory: 🟢 globální proxy, 🟡 proxy poskytovatele, 🔵 proxy připojení, vždy zobrazující IP adresu\n- **Výměna tokenů OAuth prostřednictvím proxy** – tok OAuth také prochází přes proxy, čímž se řeší `unsupported_country_region_territory`\n- **Testy připojení přes proxy** – Testy připojení používají nakonfigurovaný proxy (již žádné přímé obcházení)\n- **Podpora SOCKS5** — Plná podpora proxy SOCKS5 pro odchozí směrování\n- **TLS Fingerprint Spoofing** — Otisk prstu TLS podobný prohlížeči pomocí `wreq-js` pro obcházení detekce botů\n- **🔏 Porovnávání otisků prstů v CLI** — Změní pořadí záhlaví a polí v těle serveru tak, aby odpovídala nativním binárním podpisům v CLI, čímž drasticky snižuje riziko nahlašování účtu. IP adresa proxy je zachována — získáte současně stealth **i** maskování IP adresy.\n\n<details>\n<summary><b>🆓 4. „Chci používat umělou inteligenci pro kódování, ale nemám peníze“</b></summary>\n</details>\n\nNe každý si může dovolit zaplatit 20–200 dolarů měsíčně za předplatné AI. Studenti, vývojáři z rozvíjejících se zemí, amatéři a freelanceři potřebují přístup ke kvalitním modelům za nulovou cenu.\n\n**Jak to OmniRoute řeší:**\n\n- **Vestavění poskytovatelé bezplatné úrovně** — Nativní podpora pro 100% bezplatné poskytovatele: Qoder (5 neomezených modelů přes OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezené modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisíc tokenů/měsíc zdarma)\n- **Ollama Cloud** — Cloudově hostované modely Ollama na `api.ollama.com` s bezplatnou úrovní „Light usage“; použijte prefix `ollamacloud/<model>`\n- **Kombinace pouze zdarma** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/měsíc s nulovými prostoji\n- **NVIDIA NIM Free Access** — ~40 RPM developerský přístup k více než 70 modelům na build.nvidia.com (přechod z kreditů na čisté limity rychlosti)\n- **Strategie optimalizace nákladů** – Strategie směrování, která automaticky vybere nejlevnějšího dostupného poskytovatele\n\n<details>\n<summary><b>🔒 5. „Potřebuji chránit svou bránu umělé inteligence před neoprávněným přístupem“</b></summary>\n</details>\n\nPři zpřístupnění brány umělé inteligence síti (LAN, VPS, Docker) může kdokoli s adresou spotřebovat tokeny/kvótu vývojáře. Bez ochrany jsou API zranitelná vůči zneužití, prompt injection a dalšímu zneužití.\n\n**Jak to OmniRoute řeší:**\n\n- **Správa klíčů API** – generování, rotace a vymezování rozsahu pro každého poskytovatele s vyhrazenou stránkou `/dashboard/api-manager`\n- **Oprávnění na úrovni modelu** – Omezení klíčů API na konkrétní modely ( `openai/*` , zástupné znaky) pomocí přepínače Povolit vše/Omezit\n- **Ochrana koncových bodů API** – Vyžaduje klíč pro `/v1/models` a blokuje konkrétní poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** — Všechny trasy dashboardu chráněné middlewarem `withAuth` + tokeny CSRF\n- **Omezovač rychlosti** — Omezování rychlosti na IP s konfigurovatelnými okny\n- **Filtrování IP adres** — Seznam povolených/blokovaných adres pro řízení přístupu\n- **Ochrana proti vkládání výzev** – Sanitizace proti škodlivým vzorcům výzev\n- **Šifrování AES-256-GCM** – přihlašovací údaje jsou v klidovém stavu šifrovány\n\n<details>\n<summary><b>🛑 6. „Můj poskytovatel selhal a já ztratil/a programovací tok“</b></summary>\n</details>\n\nPoskytovatelé umělé inteligence se mohou stát nestabilními, vracet chyby 5xx nebo dosáhnout dočasných limitů rychlosti. Pokud je vývojář závislý na jediném poskytovateli, je jeho práce přerušena. Bez jističů může opakované pokusy vést k pádu aplikace.\n\n**Jak to OmniRoute řeší:**\n\n- **Jistič pro každý model** – Automatické otevírání/zavírání s konfigurovatelnými prahovými hodnotami a dobou ochlazování (Zavřeno/Otevřeno/Poloviční otevření), rozsah definovaný pro každý model, aby se zabránilo kaskádování bloků\n- **Exponenciální odklad** — Progresivní zpoždění opakování\n- **Anti-Thundering Herd** — ochrana Mutex + semafor proti souběžným bouřím s opakovanými pokusy\n- **Kombinované záložní řetězce** – Pokud primární poskytovatel selže, automaticky se propadne řetězcem bez zásahu.\n- **Kombinovaný jistič** – Automaticky deaktivuje selhávajícího poskytovatele v rámci kombinovaného řetězce\n- **Dashboard stavu** — Monitorování provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti, latence p50/p95/p99\n\n<details>\n<summary><b>🔧 7. „Konfigurace každého nástroje umělé inteligence je zdlouhavá a opakující se“</b></summary>\n</details>\n\nVývojáři používají Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Každý nástroj potřebuje jinou konfiguraci (API endpoint, klíč, model). Překonfigurování při změně poskytovatele nebo modelu je ztráta času.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel nástrojů CLI** — Vyhrazená stránka s nastavením jedním kliknutím pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generátor konfigurace GitHub Copilot** – Generuje `chatLanguageModels.json` pro VS Code s hromadným výběrem modelu\n- **Průvodce zaváděním** – 4krokové nastavení pro začínající uživatele\n- **Jeden koncový bod, všechny modely** – jednou nakonfigurujte `http://localhost:20128/v1` a získejte přístup k více než 44 poskytovatelům\n\n<details>\n<summary><b>🔑 8. „Správa OAuth tokenů od více poskytovatelů je peklo“</b></summary>\n</details>\n\nClaude Code, Codex, Gemini CLI, Copilot – všechny používají OAuth 2.0 s tokeny s vypršením platnosti. Vývojáři se musí neustále znovu autentizovat, řešit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdálených serverech. Obzvláště problematický je OAuth v LAN/VPS.\n\n**Jak to OmniRoute řeší:**\n\n- **Automatická aktualizace tokenů** – Tokeny OAuth se obnovují na pozadí před vypršením platnosti.\n- **Vestavěný OAuth 2.0 (PKCE)** – Automatický tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Více účtů na poskytovatele prostřednictvím extrakce tokenů JWT/ID\n- **OAuth LAN/Remote Fix** — Detekce privátní IP adresy pro `redirect_uri` + manuální režim URL pro vzdálené servery\n- **OAuth Behind Nginx** — Používá `window.location.origin` pro kompatibilitu s reverzní proxy\n- **Průvodce vzdáleným OAuth** – Podrobný návod k přihlašovacím údajům Google Cloud na VPS/Dockeru\n\n<details>\n<summary><b>📊 9. „Nevím, kolik utrácím ani kde“</b></summary>\n</details>\n\nVývojáři používají více placených poskytovatelů, ale nemají jednotný přehled o výdajích. Každý poskytovatel má svůj vlastní fakturační panel, ale neexistuje žádný konsolidovaný přehled. Mohou se hromadit neočekávané náklady.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard pro analýzu nákladů** – Sledování nákladů na token a správa rozpočtu pro každého poskytovatele\n- **Rozpočtové limity na úroveň** – Strop výdajů na úroveň, který spouští automatický záložní režim\n- **Konfigurace cen podle modelu** – Konfigurovatelné ceny podle modelu\n- **Statistiky použití pro každý klíč API** — Počet požadavků a časové razítko posledního použití pro každý klíč\n- **Analytický panel** – Statistické karty, graf využití modelu, tabulka poskytovatelů s mírou úspěšnosti a latencí\n\n<details>\n<summary><b>🐛 10. „Nedokážu diagnostikovat chyby a problémy ve volání umělé inteligence.“</b></summary>\n</details>\n\nKdyž volání selže, vývojář neví, zda se jednalo o limit rychlosti, vypršelý token, špatný formát nebo chybu poskytovatele. Fragmentované protokoly napříč různými terminály. Bez sledovatelnosti je ladění metodou pokus-omyl.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel jednotných protokolů** – 4 karty: Protokoly požadavků, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlížeč protokolů konzole** — Prohlížeč protokolů v reálném čase ve stylu terminálu s barevně kódovanými úrovněmi, automatickým posouváním, vyhledáváním a filtrováním\n- **Protokoly proxy SQLite** – trvalé protokoly, které přežijí restart serveru\n- **Překladačské hřiště** — 4 režimy ladění: Hřiště (překlad formátu), Tester chatu (okružní), Testovací stůl (dávkový), Živý monitor (v reálném čase)\n- **Telemetrie požadavků** — latence p50/p95/p99 + trasování X-Request-Id\n- **Souborové protokolování s rotací** – Konzolový interceptor zachycuje vše do protokolu JSON s rotací na základě velikosti\n- **Zpráva o systémových informacích** — příkaz `npm run system-info` vygeneruje `system-info.txt` s kompletním popisem vašeho prostředí (verze uzlu, verze OmniRoute, operační systém, nástroje CLI, stav Dockeru/PM2). Přiložte jej při hlášení problémů pro okamžité třídění.\n\n<details>\n<summary><b>🏗️ 11. „Nasazení a údržba brány je složitá“</b></summary>\n</details>\n\nInstalace, konfigurace a údržba AI proxy v různých prostředích (lokální, VPS, Docker, cloud) je pracná. Problémy, jako jsou pevně zakódované cesty, `EACCES` u adresářů, konflikty portů a multiplatformní sestavení, přispívají k obtížím.\n\n**Jak to OmniRoute řeší:**\n\n- **npm globální instalace** — `npm install -g omniroute && omniroute` — hotovo\n- **Docker Multi-Platform** — AMD64 + nativní ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** — `base` (bez nástrojů CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopová aplikace Electron** — Nativní aplikace pro Windows/macOS/Linux se systémovou lištou, automatickým spuštěním a offline režimem\n- **Režim rozdělených portů** – API a řídicí panel na samostatných portech pro pokročilé scénáře (reverzní proxy, síťování kontejnerů)\n- **Cloud Sync** – Konfigurace synchronizace mezi zařízeními pomocí Cloudflare Workers\n- **Zálohy databází** — Automatické zálohování, obnovení, export a import všech nastavení\n\n<details>\n<summary><b>🌍 12. „Rozhraní je pouze v angličtině a můj tým nemluví anglicky“</b></summary>\n</details>\n\nTýmy v neanglicky mluvících zemích, zejména v Latinské Americe, Asii a Evropě, se potýkají s rozhraními pouze v angličtině. Jazykové bariéry snižují míru přijetí a zvyšují chyby v konfiguraci.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard i18n — 30 jazyků** — Všech 500+ kláves je přeloženo včetně arabštiny, bulharštiny, dánštiny, němčiny, španělštiny, finštiny, francouzštiny, hebrejštiny, hindštiny, maďarštiny, indonéštiny, italštiny, japonštiny, korejštiny, malajštiny, holandštiny, norštiny, polštiny, portugalštiny (PT/BR), rumunštiny, ruštiny, slovenštiny, švédštiny, thajštiny, ukrajinštiny, vietnamštiny, čínštiny, filipínštiny a angličtiny\n- **Podpora RTL** – Podpora psaní zprava doleva pro arabštinu a hebrejštinu\n- **Vícejazyčné soubory README** — 30 kompletních překladů dokumentace\n- **Výběr jazyka** — Ikona glóbu v záhlaví pro přepínání v reálném čase\n\n<details>\n<summary><b>🔄 13. „Potřebuji víc než jen chat – potřebuji vložené soubory, obrázky, zvuk.“</b></summary>\n</details>\n\nUmělá inteligence není jen dokončování chatu. Vývojáři potřebují generovat obrázky, přepisovat zvuk, vytvářet embeddedy pro RAG, měnit pořadí dokumentů a moderovat obsah. Každé API má jiný koncový bod a formát.\n\n**Jak to OmniRoute řeší:**\n\n- **Vkládání** — `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generování obrázků** — `/v1/images/generations` s 10 poskytovateli a více než 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Převod textu na video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Převod textu na hudbu** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Přepis zvuku** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Převod textu na řeč** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a další stávající poskytovatelé\n- **Moderování** — `/v1/moderations` — Kontroly bezpečnosti obsahu\n- **Změna pořadí** — `/v1/rerank` — Změna pořadí relevance dokumentu\n- **Responses API** — Plná podpora `/v1/responses` pro Codex\n\n<details>\n<summary><b>🧪 14. „Nemám způsob, jak testovat a porovnávat kvalitu napříč modely.“</b></summary>\n</details>\n\nVývojáři chtějí vědět, který model je pro jejich případ použití nejlepší – kód, překlad, uvažování – ale ruční porovnávání je pomalé. Neexistují žádné integrované nástroje pro vyhodnocování.\n\n**Jak to OmniRoute řeší:**\n\n- **Hodnocení LLM** — Testování Golden setu s 10 předinstalovanými případy zahrnujícími pozdravy, matematiku, geografii, generování kódu, dodržování JSON, překlad, markdown, odmítnutí bezpečnostních požadavků\n- **4 strategie shody** — `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovací lavice pro překladatelské hřiště** — Dávkové testování s více vstupy a očekávanými výstupy, porovnání napříč poskytovateli\n- **Tester chatu** — Kompletní okružní cesta s vizuálním vykreslováním odpovědí\n- **Živý monitor** — Stream všech požadavků procházejících proxy serverem v reálném čase\n\n<details>\n<summary><b>📈 15. „Potřebuji škálovat bez ztráty výkonu“</b></summary>\n</details>\n\nS rostoucím objemem požadavků generují stejné otázky bez ukládání do mezipaměti duplicitní náklady. Bez idempotence duplicitní požadavky plýtvají zpracováním. Je nutné dodržovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute řeší:**\n\n- **Sémantická mezipaměť** — Dvouvrstvá mezipaměť (signatura + sémantika) snižuje náklady a latenci\n- **Idempotence požadavku** — 5s deduplikační okno pro identické požadavky\n- **Detekce limitu rychlosti** – sledování otáček za minutu (RPM), minimální mezera a maximální souběžné sledování pro každého poskytovatele\n- **Upravitelné limity rychlosti** — Konfigurovatelné výchozí hodnoty v Nastavení → Odolnost s perzistencí\n- **Mezipaměť pro ověření klíčů API** — třívrstvá mezipaměť pro výkon produkčního prostředí\n- **Dashboard s telemetrií** – latence p50/p95/p99, statistiky mezipaměti, dostupnost\n\n<details>\n<summary><b>🤖 16. „Chci mít chování modelů globálně pod kontrolou“</b></summary>\n</details>\n\nVývojáři, kteří chtějí všechny odpovědi v určitém jazyce, se specifickým tónem nebo chtějí omezit tokeny pro uvažování. Konfigurace této funkce v každém nástroji/požadavku je nepraktická.\n\n**Jak to OmniRoute řeší:**\n\n- **Vložení systémového prompt** – Globální prompt aplikovaný na všechny požadavky\n- **Validace rozpočtu Thinking** — Řízení alokace tokenů na požadavek (průchozí, automatické, vlastní, adaptivní)\n- **6 strategií směrování** – Globální strategie, které určují, jak jsou požadavky distribuovány\n- **Směrovač se zástupnými znaky** — vzory `provider/*` dynamicky směrují k libovolnému poskytovateli\n- **Přepínání povolení/zakázání kombinací** – Přepínání kombinací přímo z řídicího panelu\n- **Přepínání poskytovatele** – Povolení/zakázání všech připojení pro poskytovatele jedním kliknutím\n- **Blokovaní poskytovatelé** – Vyloučení konkrétních poskytovatelů ze seznamu `/v1/models`\n\n<details>\n<summary><b>🧰 17. „Potřebuji nástroje MCP jako prvotřídní produktové funkce.“</b></summary>\n</details>\n\nMnoho bran umělé inteligence odhaluje MCP pouze jako skrytý implementační detail. Týmy potřebují viditelnou a spravovatelnou operační vrstvu.\n\n**Jak to OmniRoute řeší:**\n\n- MCP se zobrazuje v navigaci na řídicím panelu a na kartě protokolu koncového bodu.\n- Vyhrazená stránka pro správu MCP s procesy, nástroji, rozsahy a auditem\n- Vestavěný rychlý start pro `omniroute --mcp` a onboarding klienta\n\n<details>\n<summary><b>🧠 18. „Potřebuji orchestraci A2A se synchronizací a cestami úloh streamu.“</b></summary>\n</details>\n\nPracovní postupy agentů vyžadují jak přímé odpovědi, tak dlouhodobé streamované provádění s kontrolou životního cyklu.\n\n**Jak to OmniRoute řeší:**\n\n- Koncový bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamování SSE s šířením stavu terminálu\n- Rozhraní API životního cyklu úloh pro `tasks/get` a `tasks/cancel`\n\n<details>\n<summary><b>🛰️ 19. „Potřebuji skutečný stav procesu MCP, ne odhadovaný stav.“</b></summary>\n</details>\n\nProvozní týmy potřebují vědět, zda je MCP skutečně aktivní, nejen zda je API dosažitelné.\n\n**Jak to OmniRoute řeší:**\n\n- Soubor běhového heartbeatu s PID, časovými razítky, transportem, počtem nástrojů a režimem rozsahu\n- API stavu MCP kombinující prezenční signál a nedávnou aktivitu\n- Karty stavu uživatelského rozhraní pro zobrazení aktuálnosti procesů/provozuschopnosti/prezenčního signálu\n\n<details>\n<summary><b>📋 20. „Potřebuji auditovatelné provedení nástroje MCP“</b></summary>\n</details>\n\nKdyž nástroje mění konfiguraci nebo spouštějí operační akce, týmy potřebují forenzní sledovatelnost.\n\n**Jak to OmniRoute řeší:**\n\n- Protokolování auditu pro volání nástrojů MCP s podporou SQLite\n- Filtruje podle nástroje, úspěchu/neúspěchu, klíče API a stránkování\n- Tabulka auditu dashboardu + koncové body statistik pro automatizaci\n\n<details>\n<summary><b>🔐 21. „Potřebuji omezená oprávnění MCP pro každou integraci.“</b></summary>\n</details>\n\nRůzní klienti by měli mít přístup ke kategoriím nástrojů s nejnižšími oprávněními.\n\n**Jak to OmniRoute řeší:**\n\n- 9 detailních MCP sond pro kontrolovaný přístup k nástrojům\n- Vynucení rozsahu a viditelnost v uživatelském rozhraní správy MCP\n- Bezpečná výchozí poloha pro provozní nástroje\n\n<details>\n<summary><b>⚙️ 22. „Potřebuji provozní kontroly bez nutnosti přesouvání“</b></summary>\n</details>\n\nTýmy potřebují rychlé změny v běhovém prostředí během incidentů nebo nákladových událostí.\n\n**Jak to OmniRoute řeší:**\n\n- Přepněte aktivaci komba přímo z řídicího panelu MCP\n- Používejte profily odolnosti z předdefinovaných balíčků zásad\n- Resetujte stav jističe ze stejného ovládacího panelu\n\n<details>\n<summary><b>🔄 23. „Potřebuji živý přehled o životním cyklu úkolů A2A a jejich zrušení.“</b></summary>\n</details>\n\nBez přehledu o životním cyklu je obtížné třídit incidenty úkolů.\n\n**Jak to OmniRoute řeší:**\n\n- Výpis/filtrování úkolů podle státu/dovednosti s stránkováním\n- Podrobný přehled metadat úloh, událostí a artefaktů\n- Koncový bod zrušení úlohy a akce uživatelského rozhraní s potvrzením\n\n<details>\n<summary><b>🌊 24. „Potřebuji metriky aktivního streamu pro A2A zátěž“</b></summary>\n</details>\n\nStreamovací pracovní postupy vyžadují provozní přehled o souběžnosti a živých připojeních.\n\n**Jak to OmniRoute řeší:**\n\n- Čítače aktivních streamů integrované do stavu A2A\n- Časové razítko posledního úkolu a počty pro jednotlivé stavy\n- Karty A2A dashboardu pro monitorování provozu v reálném čase\n\n<details>\n<summary><b>🪪 25. „Potřebuji standardní vyhledávání agentů pro klienty“</b></summary>\n</details>\n\nExterní klienti a orchestratoři potřebují pro onboarding strojově čitelná metadata.\n\n**Jak to OmniRoute řeší:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazené v uživatelském rozhraní pro správu\n- API pro stav A2A zahrnuje metadata pro zjišťování pro automatizaci\n\n<details>\n<summary><b>🧭 26. „Potřebuji v uživatelském rozhraní produktu zjistitelnost protokolu.“</b></summary>\n</details>\n\nPokud uživatelé nemohou objevit protokolové povrchy, kvalita přijetí a podpory klesá.\n\n**Jak to OmniRoute řeší:**\n\n- Stránka Konsolidované **koncové body** s kartami pro koncové body Proxy, MCP, A2A a API\n- Přepínání stavu inline služby (Online/Offline) pro MCP a A2A\n- Odkazy z přehledu na vyhrazené karty pro správu\n\n<details>\n<summary><b>🧪 27. „Potřebuji komplexní ověření protokolu se skutečnými klienty.“</b></summary>\n</details>\n\nSimulované testy nestačí k ověření kompatibility protokolu před vydáním.\n\n**Jak to OmniRoute řeší:**\n\n- Sada E2E, která spouští aplikaci a používá skutečný transport klienta MCP SDK.\n- Klientské testy A2A pro toky zjišťování, odesílání, streamování, načítání a zrušení\n- Křížová kontrola tvrzení oproti API pro audit MCP a úkoly A2A\n\n<details>\n<summary><b>📡 28. „Potřebuji jednotnou pozorovatelnost napříč všemi rozhraními“</b></summary>\n</details>\n\nRozdělení pozorovatelnosti podle protokolu vytváří slepá místa a delší MTTR.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocené dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie požadavků napříč vrstvami OpenAI, MCP a A2A\n- Provozní API pro stav a automatizaci\n\n<details>\n<summary><b>💼 29. „Potřebuji jeden runtime pro proxy + nástroje + orchestraci agentů“</b></summary>\n</details>\n\nSpouštění mnoha samostatných služeb zvyšuje provozní náklady a počet poruch.\n\n**Jak to OmniRoute řeší:**\n\n- Proxy, MCP server a A2A server kompatibilní s OpenAI v jednom balíčku\n- Sdílené ověřování, odolnost, úložiště dat a pozorovatelnost\n- Konzistentní model politik napříč všemi interakčními plochami\n\n<details>\n<summary><b>🚀 30. „Potřebuji agentské pracovní postupy bez slepení kódu.“</b></summary>\n</details>\n\nTýmy ztrácejí rychlost při spojování více ad-hoc služeb a skriptů.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocená strategie koncových bodů pro klienty a agenty\n- Vestavěná uživatelská rozhraní pro správu protokolů a cesty pro ověřování kouře\n- Základy připravené pro produkční prostředí (zabezpečení, protokolování, odolnost, zálohování)\n\n### Příklady herních plánů (integrované případy užití)\n\n**Příručka A: Maximalizace placeného předplatného + levné zálohování**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Příručka B: Kódovací stack s nulovými náklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Příručka C: Nonstop záložní řetězec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Příručka D: Operace agentů s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Začněte zdarma — Nulové náklady na konfiguraci\n\n> Nastavte si kódování s umělou inteligencí během několika minut za **0 $/měsíc** . Propojte tyto bezplatné účty a využijte vestavěnou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelé odemčeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Připojení **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 – **neomezeně** |\n| 2 | Připojení k **Qoder** (Google OAuth) | kimi-k2-myšlení, qwen3-coder-plus, deepseek-r1... — **neomezeně** |\n| 3 | Připojení **Qwen** (kód zařízení) | qwen3-coder-plus, qwen3-coder-flash... — **neomezeně** |\n| 4 | Připojení **rozhraní příkazového řádku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180 000 GBP/měsíc zdarma** |\n| 5 | `/dashboard/combos` → Šablona **Free Stack (0 $)** | Automatické zařazení všech bezplatných poskytovatelů do routingu |\n\n**V libovolném IDE/CLI naveďte:** `http://localhost:20128/v1` · Klíč API: `any-string` · Hotovo.\n\n> **Volitelné doplňkové krytí (také zdarma):** Groq API klíč (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelů), Cerebras (1 milion tok/den).\n\n## ⚡ Rychlý start\n\n### 1) Nainstalujte a spusťte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uživatelé pnpm:** Po instalaci spusťte `pnpm approve-builds -g` , abyste povolili nativní skripty pro sestavení vyžadované programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard se otevírá na `http://localhost:20128` a základní URL API je `http://localhost:20128/v1` .\n\n| Příkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuštění serveru ( `PORT=20128` , API a dashboard na stejném portu) |\n| `omniroute --port 3000` | Nastavte kanonický/API port na 3000 |\n| `omniroute --mcp` | Spuštění MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevírat prohlížeč automaticky |\n| `omniroute --help` | Zobrazit nápovědu |\n\nVolitelný režim s rozděleným portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Připojte poskytovatele a vytvořte si klíč API\n\n1. Otevřete Dashboard → `Providers` a připojte alespoň jednoho poskytovatele (klíč OAuth nebo API).\n2. Otevřete Dashboard → `Endpoints` a vytvořte API klíč.\n3. (Volitelné) Otevřete Dashboard → `Combos` a nastavte záložní řetězec.\n\n### 3) Nasměrujte svůj kódovací nástroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilními s OpenAI.\n\n### 4) Povolení a ověření protokolů (v2.0)\n\n**MCP (pro operace řízené nástroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak připojte svého MCP klienta přes `stdio` a otestujte nástroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovní postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ověřte vše od začátku do konce (doporučeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ověřuje skutečné toky klientů MCP a A2A v porovnání se spuštěnou aplikací.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## 🐳 Docker\n\nOmniRoute je k dispozici jako veřejný obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlý běh:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostředí:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Používání Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | Štítek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovější stabilní verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuální verze |\n\n---\n\n## 🖥️ Desktopová aplikace – offline a vždy zapnutá\n\n> 🆕 **NOVINKA!** OmniRoute je nyní k dispozici jako **nativní desktopová aplikace** pro Windows, macOS a Linux.\n\nSpusťte OmniRoute jako samostatnou desktopovou aplikaci – pro lokální modely není potřeba žádný terminál, prohlížeč ani internet. Aplikace založená na platformě Electron obsahuje:\n\n- 🖥️ **Nativní okno** — Vyhrazené okno aplikace s integrací do systémové lišty\n- 🔄 **Automatické spuštění** — Spuštění OmniRoute po přihlášení do systému\n- 🔔 **Nativní oznámení** – Získejte upozornění na vyčerpání kvóty nebo problémy s poskytovateli\n- ⚡ **Instalace jedním kliknutím** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline režim** — Funguje plně offline s přiloženým serverem\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systémový zásobník\n\nPo minimalizaci se OmniRoute nachází v systémové liště a nabízí rychlé akce:\n\n- Otevřít řídicí panel\n- Změnit port serveru\n- Ukončit aplikaci\n\n📖 Úplná dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Přehled cen\n\n| Úroveň | Poskytovatel | Náklady | Obnovení kvóty | Nejlepší pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **💳 PŘEDPLATNÉ** | Claude Code (profesionál) | 20 dolarů měsíčně | 5 hodin + týdně | Již přihlášen/a k odběru |\n| Kodex (Plus/Pro) | 20–200 USD/měsíc | 5 hodin + týdně | Uživatelé OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisíc měsíčně + 1 tisíc denně | Každý! |\n| GitHub Copilot | 10–19 USD/měsíc | Měsíční | Uživatelé GitHubu |\n| **🔑 KLÍČ API** | NVIDIA NIM | **ZDARMA** (vývoj navždy) | ~40 ot./min | 70+ otevřených modelů |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší na světě |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisíc otáček za minutu | Ultrarychlá lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | Žádný | Nejlepší zdůvodnění ceny a kvality |\n| xAI Grok-4 Rychlý | **0,20/0,50 USD za 1 milion** 🆕 | Žádný | Nejrychlejší + volání nástroje, ultranízké |\n| xAI Grok-4 (standardní) | 0,20/1,50 USD za 1 milion 🆕 | Žádný | Vlajková loď Reasoning od xAI |\n| Mistral | Zkušební verze zdarma + placené | Omezená sazba | Evropská umělá inteligence |\n| OpenRouter | Platba za použití | Žádný | Více než 100 modelů agregováno. |\n| **💰 LEVNÉ** | GLM-5 (přes Z.AI) 🆕 | 0,5 USD/1 milion | Denně v 10:00 | Výstup 128 tisíc obrazových bodů, nejnovější vlajková loď |\n| GLM-4.7 | 0,6 USD/1 milion | Denně v 10:00 | Záloha rozpočtu |\n| MiniMax M2.5 🆕 | Vstup 0,3 USD/1 milion | 5hodinové válcování | Úvaha + agentní úkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinové válcování | Nejlevnější varianta |\n| Kimi K2.5 (Moonshot API) 🆕 | Platba za použití | Žádný | Přímý přístup k Moonshot API |\n| Kimi K2 | 9 dolarů měsíčně bez závazků | 10 milionů tokenů/měsíc | Předvídatelné náklady |\n| **🆓 ZDARMA** | Qoder | **0 dolarů** | Neomezený | 5 modelů neomezeně |\n| Qwen | **0 dolarů** | Neomezený | 4 modely neomezeně |\n| Kiro | **0 dolarů** | Neomezený | Claude Sonnet/Haiku (tvorce AWS) |\n\n> 🆕 **Přidány nové modely (březen 2026):** řada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkováno na 1143 ms – o 30 % rychlejší než Gemini 2.5 Flash), GLM-5 přes Z.AI s výstupem 128K, uvažování MiniMax M2.5, aktualizované ceny DeepSeek V3.2, Kimi K2.5 přes Moonshot Direct API.\n\n**💡 Kombinovaný balík za 0 $ — Kompletní bezplatná instalace:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Nulové náklady. Nikdy nepřestávejte s kódováním.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a všechny záložní režimy se provede automaticky – žádné ruční přepínání.\n\n---\n\n---\n\n## 🆓 Bezplatné modely – Co skutečně získáte\n\n> Všechny níže uvedené modely jsou **100% zdarma a nevyžadují žádnou kreditní kartu** . OmniRoute mezi nimi automaticky propojí trasy, když dojde jedna kvóta – zkombinujte je všechny a získejte tak nerozlučnou kombinaci za 0 dolarů.\n\n### 🔵 CLAUDE MODELS (přes Kiro — AWS Builder ID)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-opus-4.6` | `kr/` | **Neomezený** | Nejnovější opus od Kira |\n\n### 🟢 MODELY QODER (Bezplatné OAuth — bez nutnosti platit kreditní kartou)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-plus` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `deepseek-r1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `minimax-m2.1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `kimi-k2` | `if/` | **Neomezený** | Žádný hlášený strop |\n\n### 🟡 MODELY QWEN (Ověření kódu zařízení)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-next` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `vision-model` | `qw/` | **Neomezený** | Multimodální (obrázky) |\n\n### 🟣 Rozhraní GEMINI CLI (Google OAuth)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisíc tok/měsíc** + 1 tisíc/den | Měsíční reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisíc měsíčně (sdílený bazén) | Vysoká kvalita |\n\n### ⚫ NVIDIA NIM (Bezplatný klíč API — build.nvidia.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vývojář) | Žádný limit tokenů | **~40 ot./min** | Více než 70 modelů; přechod na čisté limity sazeb v polovině roku 2025 |\n\nOblíbené bezplatné modely: `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`\n\n### ⚪ CEREBRAS (Bezplatný klíč API — inference.cerebras.ai)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenů/den** | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší inference LLM na světě; denně se resetuje |\n\nDostupné zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Bezplatný API klíč — console.groq.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisíc otáček za minutu** | 30 ot./min na model | Žádná kreditní karta; limit 429, neúčtováno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **💡 Ultimátní bezplatný zásobník:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> → Qoder (5 models, unlimited)\n> → Qwen (4 models, unlimited)\n> → Gemini CLI (180K/mo)\n> → Cerebras (1M tok/day)\n> → Groq (14.4K req/day)\n> → NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a už nikdy nebudete platit za umělou inteligenci.\n\n## 🎙️ Kombinovaná transkripce zdarma\n\n> Přepisujte libovolné audio/video za **0 $** – Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako záložní nástroj, Groq Whisper jako neomezená nouzová záloha.\n\n| Poskytovatel | Bezplatné kredity | Nejlepší model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| 🟢 **Deepgram** | **200 dolarů zdarma** (registrace) | `nova-3` — nejvyšší přesnost, více než 30 jazyků | Žádný limit RPM pro kredity zdarma |\n| 🔵 **AssemblyAI** | **50 dolarů zdarma** (registrace) | `universal-3-pro` — kapitoly, sentiment, osobní údaje | Žádný limit RPM pro kredity zdarma |\n| 🔴 **Groq** | **Navždy zdarma** | `whisper-large-v3` — OpenAI Šepot | 30 ot./min (omezená rychlost) |\n\n**Navrhovaná kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nPak v `/dashboard/media` → záložka **Přepis** : nahrajte libovolný zvukový nebo video soubor → vyberte kombinovaný koncový bod → získejte přepis v podporovaných formátech.\n\n## 💡 Klíčové vlastnosti\n\nOmniRoute v2.0 je navržen jako operační platforma, nikoli pouze jako proxy pro relé.\n\n### 🤖 Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dělá |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **MCP Server (16 nástrojů)** | Nástroje IDE/agent prostřednictvím 3 transportů: stdio, SSE ( `/api/mcp/sse` ), Streamovatelný HTTP ( `/api/mcp/stream` ) |\n| 🤝 **A2A server (JSON-RPC + SSE)** | Spouštění úloh mezi agenty se synchronizací a streamováním |\n| 🧭 **Konsolidovaná stránka koncových bodů** | Stránka pro správu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| 🎚️ **Přepínače pro povolení/zakázání služby** | Přepínače ZAP/VYP pro MCP a A2A s trvalým nastavením (výchozí: VYP) |\n| 🛰️ **Srdeční tep za běhu MCP** | Skutečný stav procesu (pid, doba provozuschopnosti, stáří heartbeatu, transport, režim rozsahu) |\n| 📋 **Auditní záznam MCP** | Filtrovatelné protokoly auditu s hodnocením úspěchu/neúspěchu a klíčovým přiřazením |\n| 🔐 **Vynucování rozsahu MCP** | 9 podrobných oprávnění pro řízený přístup k nástrojům |\n| 📡 **Správa životního cyklu úkolů A2A** | Seznam/filtrování úloh, kontrola událostí/artefaktů, zrušení spuštěných úloh |\n| 📋 **Objevení karty agenta** | `/.well-known/agent.json` pro automatické vyhledávání klientů |\n| 🧪 **Testovací postroj Protocol E2E** | Skutečné MCP SDK + toky klientů A2A v `test:protocols:e2e` |\n| ⚙️ **Provozní kontroly** | Kombinace přepínačů, použití profilů odolnosti, resetování jističů z jednoho ovládacího panelu |\n\n### 🧠 Směrování a inteligence\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| 🎯 **Inteligentní čtyřúrovňový záložní systém** | Automatická trasa: Předplatné → API klíč → Levné → Zdarma |\n| 📊 **Sledování kvót v reálném čase** | Počet tokenů v reálném čase + odpočet resetování pro každého poskytovatele |\n| 🔄 **Překlad formátu** | OpenAI ↔ Claude ↔ Gemini ↔ Odpovědi s konverzemi bezpečnými pro schéma |\n| 👥 **Podpora více účtů** | Více účtů na poskytovatele s inteligentním výběrem |\n| 🔄 **Automatická aktualizace tokenů** | Tokeny OAuth se automaticky obnovují při opakovaném pokusu. |\n| 🎨 **Vlastní kombinace** | 6 vyvažovacích strategií + řízení záložního řetězce |\n| 🌐 **Směrovač se zástupnými znaky** | dynamické směrování `provider/*` |\n| 🧠 **Přemýšlení o rozpočtových kontrolách** | Limity pro průchozí, automatické, vlastní a adaptivní uvažování |\n| 🔀 **Aliasy modelů** | Vestavěné + vlastní aliasování modelů a bezpečnost migrace |\n| ⚡ **Degradace pozadí** | Směrujte úlohy na pozadí s nízkou prioritou na levnější modely |\n| 🧪 **Chytré směrování s ohledem na úkoly** | Automatický výběr modelu podle typu obsahu (kódování/vize/analýza/sumarizace) |\n| 💬 **Vstřikování do systému** | Globální kontroly chování uplatňované konzistentně |\n| 📄 **Kompatibilita API pro odpovědi** | Plná podpora `/v1/responses` pro Codex a pokročilé agentické pracovní postupy |\n\n### 🎵 Multimodální API\n\n| Funkce | Co to dělá |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Generování obrázků** | `/v1/images/generations` s cloudovým a lokálním backendem |\n| 📐 **Vložení** | `/v1/embeddings` pro vyhledávání a RAG pipelines |\n| 🎤 **Přepis zvuku** | `/v1/audio/transcriptions` (Whisper a další poskytovatelé) |\n| 🔊 **Převod textu na řeč** | `/v1/audio/speech` (více enginů/poskytovatelů) |\n| 🎬 **Generování videa** | `/v1/videos/generations` (pracovní postupy ComfyUI + SD WebUI) |\n| 🎵 **Hudební generace** | `/v1/music/generations` (pracovní postupy ComfyUI) |\n| 🛡️ **Moderování** | Bezpečnostní kontroly `/v1/moderations` |\n| 🔀 **Změna pořadí** | `/v1/rerank` pro hodnocení relevance |\n| 🔍 **Vyhledávání na webu** 🆕 | `/v1/search` — 5 poskytovatelů (Serper, Brave, Perplexity, Exa, Tavily), více než 6 500 zdarma/měsíc, automatické přepnutí na záložní systém, mezipaměť |\n\n### 🛡️ Odolnost, bezpečnost a správa věcí veřejných\n\n| Funkce | Co to dělá |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| 🔌 **Jističe** | Vypnutí/obnovení pro každý model s ovládáním prahových hodnot |\n| 🎯 **Modely s ohledem na koncové body** | Vlastní modely deklarují podporované koncové body + formát API |\n| 🛡️ **Stádo proti hromům** | Ochrana mutexu a semaforu při událostech opakování/rychlosti |\n| 🧠 **Sémantická + podpisová mezipaměť** | Snížení nákladů/latence díky dvěma vrstvám mezipaměti |\n| ⚡ **Žádost o idempotenci** | Okno ochrany proti duplikacím |\n| 🔒 **Falšování otisků prstů pomocí TLS** | Otisk TLS podobný prohlížeči – **snižuje detekci botů a nahlašování účtů** |\n| 🔏 **Porovnávání otisků prstů v CLI** | Shoduje se s nativními podpisy požadavků CLI – **snižuje riziko zablokování a zároveň zachovává IP adresu proxy** |\n| 🌐 **Filtrování IP adres** | Ovládání seznamu povolených/blokovaných položek pro odhalená nasazení |\n| 📊 **Upravitelné limity rychlosti** | Konfigurovatelné globální/na úrovni poskytovatele limity s perzistencí |\n| 🔑 **Správa klíčů API a stanovení rozsahu** | Bezpečné vydávání/rotace klíčů a kontroly modelu/poskytovatele |\n| 🛡️ **Chráněné `/models`** | Volitelné ověřování a skrytí poskytovatele pro katalog modelů |\n\n### 📊 Pozorovatelnost a analytika\n\n| Funkce | Co to dělá |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| 📝 **Žádost + protokolování proxy** | Úplné protokolování požadavků/odpovědí a proxy |\n| 📋 **Sjednocený panel protokolů** | Zobrazení požadavků, proxy, auditu a konzole na jedné stránce |\n| 🔍 **Vyžádat si telemetrii** | Latence p50/p95/p99 a trasování požadavků |\n| 🏥 **Panel zdraví** | Doba provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti |\n| 💰 **Sledování nákladů** | Kontrola rozpočtu a přehled o cenách pro jednotlivé modely |\n| 📈 **Analytické vizualizace** | Přehledy využití modelů/poskytovatelů a zobrazení trendů |\n| 🧪 **Rámec hodnocení** | Testování zlaté sady s konfigurovatelnými strategiemi shody |\n\n### ☁️ Nasazení a platforma\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| 🌐 **Nasazení kdekoli** | Localhost, VPS, Docker, cloudová prostředí |\n| 💾 **Synchronizace s cloudem** | Synchronizace konfigurace přes cloud worker |\n| 🔄 **Zálohování/Obnovení** | Toky exportu/importu a obnovy po havárii |\n| 🧙 **Průvodce nástupem** | Průvodce prvním spuštěním |\n| 🔧 **Panel nástrojů CLI** | Nastavení oblíbených kódovacích nástrojů jedním kliknutím |\n| 🎮 **Modelové hřiště** | Otestujte libovolného poskytovatele/model/koncový bod z řídicího panelu |\n| 🔏 **Přepínač otisků prstů v příkazovém řádku** | Porovnávání otisků prstů podle poskytovatele v Nastavení &gt; Zabezpečení |\n| 🌐 **i18n (30 jazyků)** | Plná jazyková podpora dashboardu a dokumentace s psaním zprava doleva |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Adresář vlastních dat** | Přepsání `DATA_DIR` pro umístění úložiště |\n\n### Hluboký pohled na funkce\n\n#### Chytrá záložní funkce s praktickou kontrolou nákladů\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyž selže kvóta, rychlost nebo stav, OmniRoute automaticky přejde k dalšímu kandidátovi bez nutnosti ručního přepínání.\n\n#### Správa protokolů, která je viditelná a ovladatelná\n\n- MCP + A2A jsou viditelné v uživatelském rozhraní a dokumentaci (nejsou skryté)\n- API pro stav protokolu zpřístupňují živá provozní data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnují akce pro operace 2. dne (přepínání kombinací, resetování jističů, zrušení úkolů)\n\n#### Pracovní postup překladatele + validace\n\nOblast překladatele zahrnuje:\n\n- **Hřiště** : kontroly transformace požadavků\n- **Tester chatu** : kompletní okružní cesta požadavku/odpovědi\n- **Testovací stolice** : více případů v jednom běhu\n- **Živý monitor** : zobrazení provozu v reálném čase\n\nPlus validace protokolu se skutečnými klienty pomocí `npm run test:protocols:e2e` .\n\n> 📖 **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** — Referenční informace o nástrojích, konfigurace IDE a příklady klientů\n>\n> 📖 **[Soubor README pro A2A Server](src/lib/a2a/README.md)** — Dovednosti, metody JSON-RPC, streamování a životní cyklus úloh\n\n## 🧪 Hodnocení (Evals)\n\nOmniRoute obsahuje vestavěný hodnotící rámec pro testování kvality odpovědí LLM v porovnání se zlatou sadou. Přístup k němu je možný přes **Analýzy → Hodnocení** v dashboardu.\n\n### Vestavěná zlatá sada\n\nPředinstalovaná sada „OmniRoute Golden Set“ obsahuje testovací případy pro:\n\n- Zdravím, matematika, zeměpis, generování kódu\n- Shoda s formátem JSON, překlad, generování markdownů\n- Bezpečnostní odmítnutí (škodlivý obsah), počítání, booleovská logika\n\n### Strategie hodnocení\n\n| Strategie | Popis | Příklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Výstup se musí přesně shodovat | `\"4\"` |\n| `contains` | Výstup musí obsahovat podřetězec (bez rozlišení velkých a malých písmen) | `\"Paris\"` |\n| `regex` | Výstup musí odpovídat vzoru regulárních výrazů | `\"1.*2.*3\"` |\n| `custom` | Vlastní JS funkce vrací true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Průvodce nastavením\n\n### Nastavení protokolu (MCP + A2A)\n\n<details>\n<summary><b>🧩 Nastavení MCP (Model Context Protocol)</b></summary>\n</details>\n\nSpuštění MCP transportu v režimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporučený postup ověření:\n\n1. Připojte svého MCP klienta přes stdio.\n2. Spusťte `omniroute_get_health` .\n3. Spusťte `omniroute_list_combos` .\n4. Otevřete `/dashboard/mcp` pro ověření prezenčního signálu, aktivity a auditu.\n\nUžitečná API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n<details>\n<summary><b>🤝 Nastavení A2A (Agent2Agent)</b></summary>\n</details>\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat úkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSpráva životního cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvozní uživatelské rozhraní:\n\n- `/dashboard/a2a` pro pozorovatelnost úloh/stavů/streamů a akce kouření\n\n<details>\n<summary><b>🧪 Komplexní validace protokolu</b></summary>\n</details>\n\nOvěřte oba protokoly se skutečnými klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTím se ověřuje:\n\n- Připojení/seznam/volání klienta MCP SDK\n- A2A objevování/odesílání/streamování/získávání/zrušení\n- Křížová kontrola dat v auditu MCP a API pro správu úloh A2A\n\n<details>\n<summary><b>💳 Poskytovatelé předplatného</b></summary>\n</details>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionály:** Pro složité úkoly používejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvótu pro každý model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Správa limitů účtu Codex (5h + týdně)\n\nKaždý účet Codex má nyní přepínače zásad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinového prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zásadu týdenního prahu okna.\n- Prahové chování: když povolené okno dosáhne využití &gt;=90 %, je daný účet přeskočen.\n- Chování rotace: OmniRoute automaticky přesměruje na další způsobilý účet Codex.\n- Chování při resetování: Po `resetAt` určité doby se účet automaticky opět stane způsobilým.\n\nScénáře:\n\n- `5h ON` + `Weekly ON` : účet je přeskočen, když kterékoli z oken dosáhne prahové hodnoty.\n- `5h OFF` + `Weekly ON` : účet může být zablokován pouze týdenním používáním.\n- `5h ON` + `Weekly OFF` : účet může být zablokován pouze při 5hodinovém používání.\n- `resetAt` passed: účet se automaticky znovu zapne (bez ručního opětovného povolení).\n\n### Gemini CLI (ZDARMA 180 000/měsíc!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepší hodnota:** Obrovská bezplatná úroveň! Použijte ji před placenými úrovněmi.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n<details>\n<summary><b>🔑 Poskytovatelé klíčů API</b></summary>\n</details>\n\n### NVIDIA NIM (BEZPLATNÝ přístup pro vývojáře — více než 70 modelů)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Získejte zdarma klíč API (včetně 1000 inferenčních kreditů)\n3. Ovládací panel → Přidat poskytovatele → NVIDIA NIM:\n - Klíč API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a více než 50 dalších\n\n**Tip pro profesionály:** API kompatibilní s OpenAI – funguje bez problémů s překladem formátů OmniRoute!\n\n### Hluboké vyhledávání\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatná úroveň!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Získejte klíč API (včetně bezplatné úrovně)\n3. Ovládací panel → Přidat poskytovatele → Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionály:** Ultrarychlá inference – nejlepší pro kódování v reálném čase!\n\n### OpenRouter (100+ modelů)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → OpenRouter\n\n**Modely:** Získejte přístup k více než 100 modelům od všech hlavních poskytovatelů prostřednictvím jediného klíče API.\n\n<details>\n<summary><b>💰 Levní poskytovatelé (záložní)</b></summary>\n</details>\n\n### GLM-4.7 (Denní reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Získejte klíč API z kódovacího plánu\n3. Nástěnka → Přidat klíč API:\n - Poskytovatel: `glm`\n - Klíč API: `your-key`\n\n**Použití:** `glm/glm-4.7`\n\n**Tip pro profesionály:** Programovací plán nabízí 3× kvótu za cenu 1/7! Obnovuje se denně v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionály:** Nejlevnější varianta pro dlouhý kontext (1 milion tokenů)!\n\n### Kimi K2 (paušální poplatek 9 dolarů měsíčně)\n\n1. Odebírat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `kimi/kimi-latest`\n\n**Tip pro profesionály:** Fixních 9 $/měsíc za 10 milionů tokenů = efektivní náklady 0,90 $/1 milion!\n\n<details>\n<summary><b>🆓 BEZPLATNÍ poskytovatelé (nouzové zálohování)</b></summary>\n</details>\n\n### Qoder (5 BEZPLATNÝCH modelů přes OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kódem zařízení)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n<details>\n<summary><b>🎨 Vytvořte kombinace</b></summary>\n</details>\n\n### Příklad 1: Maximalizace předplatného → Levné zálohování\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Příklad 2: Pouze zdarma (nulové náklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n<details>\n<summary><b>🔧 Integrace s rozhraním příkazového řádku</b></summary>\n</details>\n\n### IDE kurzoru\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jedním kliknutím použijte stránku **Nástroje CLI** na řídicím panelu nebo ručně upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Možnost 1 – Dashboard (doporučeno):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Možnost 2 – Manuální úprava:** Úprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznámka:** OpenClaw funguje pouze s lokálním OmniRoute. Místo `localhost` použijte `127.0.0.1` , abyste se vyhnuli problémům s rozlišením IPv6.\n\n### Cline / Pokračovat / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Přidání OmniRoute jako vlastního poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvořte/upravte `opencode.json` v kořenovém adresáři projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` přidejte jakýkoli model dostupný ve vašem koncovém bodu OmniRoute `/v1/models` . Použijte formát `provider/model-id` z vašeho dashboardu OmniRoute.\n\n---\n\n## 🐛 Řešení problémů\n\n<details>\n<summary><b>Kliknutím rozbalíte průvodce řešením problémů</b></summary>\n</details>\n\n**\"Jazykový model neposkytoval zprávy\"**\n\n- Kvóta poskytovatele vyčerpána → Zkontrolujte sledování kvót na řídicím panelu\n- Řešení: Použijte záložní kombinovanou variantu nebo přejděte na levnější úroveň\n\n**Omezení rychlosti**\n\n- Kvóta předplatného vyčerpána → Přechod na GLM/MiniMax\n- Přidat kombo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vypršela**\n\n- Automaticky aktualizováno službou OmniRoute\n- Pokud problémy přetrvávají: Ovládací panel → Poskytovatel → Znovu připojit\n\n**Vysoké náklady**\n\n- Zkontrolujte statistiky využití v sekci Nástěnka → Náklady\n- Přepnout primární model na GLM/MiniMax\n- Pro nekritické úlohy použijte bezplatnou úroveň (Gemini CLI, Qoder).\n\n**Porty řídicího panelu/API jsou nesprávné**\n\n- `PORT` je kanonický základní port (a standardně port API)\n- `API_PORT` přepisuje pouze posluchač API kompatibilní s OpenAI.\n- `DASHBOARD_PORT` přepisuje pouze posluchač dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaši veřejnou URL adresu řídicího panelu (pro zpětná volání OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ověřte, zda `BASE_URL` odkazuje na vaši spuštěnou instanci.\n- Ověřte, zda `CLOUD_URL` odkazuje na váš očekávaný cloudový koncový bod.\n- Udržujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na straně serveru.\n\n**První přihlášení nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud není nastaveno, záložní heslo je `123456`\n\n**Žádné protokoly požadavků**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test připojení ukazuje „Neplatné“ pro poskytovatele kompatibilní s OpenAI**\n\n- Mnoho poskytovatelů nezpřístupňuje koncový bod `/models`\n- OmniRoute v1.0.6+ zahrnuje záložní ověření pomocí dokončení chatu\n- Zajistěte, aby základní URL adresa obsahovala příponu `/v1`\n\n### 🔐 OAuth na vzdáleném serveru\n\n<a name=\"oauth-on-a-remote-server\"></a>\n\n> **⚠️ Důležité pro uživatele, kteří provozují OmniRoute na VPS, Dockeru nebo jakémkoli vzdáleném serveru**\n\n#### Proč selhává OAuth v rozhraní CLI Antigravity / Gemini na vzdálených serverech?\n\nPoskytovatelé rozhraní CLI **Antigravity** a **Gemini** používají **Google OAuth 2.0** . Google vyžaduje, aby se `redirect_uri` v toku OAuth přesně shodoval s jedním z předregistrovaných URI v konzoli Google Cloud Console aplikace.\n\nPřihlašovací údaje OAuth, které jsou součástí OmniRoute, jsou registrovány **pouze pro `localhost`** . Když přistupujete k OmniRoute na vzdáleném serveru (např. `https://omniroute.myserver.com` ), Google odmítne ověření pomocí:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Řešení: Nakonfigurujte si vlastní přihlašovací údaje OAuth\n\nV Google Cloud Console je potřeba vytvořit **ID klienta OAuth 2.0** s URI vašeho serveru.\n\n#### Krok za krokem\n\n**1. Otevřete konzoli Google Cloud**\n\nPřejděte na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvořte nové ID klienta OAuth 2.0**\n\n- Klikněte na **„+ Vytvořit přihlašovací údaje“** → **„ID klienta OAuth“**\n- Typ aplikace: **„Webová aplikace“**\n- Název: cokoli chcete (např. `OmniRoute Remote` )\n\n**3. Přidejte autorizované URI pro přesměrování**\n\nDo pole **„Autorizované identifikátory URI pro přesměrování“** přidejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraďte `your-server.com` doménou nebo IP adresou vašeho serveru (v případě potřeby uveďte i port, např. `http://45.33.32.156:20128/callback` ).\n\n**4. Uložte a zkopírujte přihlašovací údaje**\n\nPo vytvoření Google zobrazí **ID klienta** a **tajný kód klienta** .\n\n**5. Nastavení proměnných prostředí**\n\nVe vašem souboru `.env` (nebo proměnných prostředí Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu připojit**\n\nŘídicí panel → Poskytovatelé → Antigravity (nebo Gemini CLI) → OAuth\n\nGoogle nyní bude správně přesměrovávat na `https://your-server.com/callback` .\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nPokud si teď nechcete nastavovat vlastní přihlašovací údaje, můžete stále použít **ruční postup pro URL** :\n\n1. OmniRoute otevírá autorizační URL od Googlu\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru).\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče (i když se stránka nenačte)\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute.\n5. Klikněte na **„Připojit“**\n\n> To funguje, protože autorizační kód v URL adrese je platný bez ohledu na to, zda se načetla přesměrovací stránka.\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nChcete-li získat přístup k přihlašovacím údajům bez vlastní konfigurace, můžete použít následující postup:\n\n1. OmniRoute otevře URL autorizace Google\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru)\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute\n5. Klikněte na **„Připojit\"**\n\n> Toto řešení funguje, protože autorizační kód v URL adrese je platný bez ohledu na načtení přesměrovací stránky.\n\n---\n\n## 🛠️ Technologický stack\n\n<details>\n<summary><b>Kliknutím rozbalíte podrobnosti o technologickém stacku</b></summary>\n</details>\n\n- **Runtime** : Node.js 18–22 LTS (⚠️ Node.js 24+ **není podporován** — nativní binární soubory `better-sqlite3` jsou nekompatibilní)\n- **Jazyk** : TypeScript 5.9 — **100% TypeScript** napříč `src/` a `open-sse/` ( `any` v základních modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databáze** : LowDB (JSON) + SQLite (stav domény + protokoly proxy + audit MCP + rozhodnutí o směrování)\n- **Schémata** : Zod (validace I/O nástrojů MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamování** : Události odeslané serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klíče + autorizace s rozsahem MCP\n- **Testování** : Node.js test runner + Vitest (900+ testů včetně unit, integračních, E2E)\n- **CI/CD** : Akce GitHubu (automatické publikování v npm + Docker Hub při vydání)\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **Balíček** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistič, exponenciální odstavení, ochrana proti hromům, falešné TLS, automatické kombinované samoopravování\n\n---\n\n## 📖 Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uživatelská příručka](docs/USER_GUIDE.md) | Poskytovatelé, kombinace, integrace CLI, nasazení |\n| [Referenční informace k API](docs/API_REFERENCE.md) | Všechny koncové body s příklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nástrojů MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamování, správa úloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorové bodování, balíčky režimů, samoléčba |\n| [Odstraňování problémů](docs/TROUBLESHOOTING.md) | Běžné problémy a jejich řešení |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a interní prvky systému |\n| [Přispívání](CONTRIBUTING.md) | Nastavení a pokyny pro vývoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpečnostní zásady](SECURITY.md) | Hlášení zranitelností a bezpečnostní postupy |\n| [Nasazení virtuálního počítače](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletní průvodce: Nastavení virtuálního počítače + nginx + Cloudflare |\n| [Galerie funkcí](docs/FEATURES.md) | Vizuální prohlídka řídicího panelu se snímky obrazovky |\n| [Kontrolní seznam vydání](docs/RELEASE_CHECKLIST.md) | Kroky ověření před vydáním |\n\n---\n\n## 🗺️ Plán\n\nOmniRoute má **v plánu více než 210 funkcí** v několika fázích vývoje. Zde jsou klíčové oblasti:\n\n| Kategorie | Plánované funkce | Hlavní body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| 🧠 **Směrování a inteligence** | 25+ | Směrování s nejnižší latencí, směrování založené na tagech, kontrola kvót před výstupem, výběr účtu P2C |\n| 🔒 **Zabezpečení a dodržování předpisů** | 20+ | Zpevnění SSRF, maskování přihlašovacích údajů, limit rychlosti pro každý koncový bod, stanovení rozsahu klíčů pro správu |\n| 📊 **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledování kvót v reálném čase, sledování nákladů podle modelu |\n| 🔄 **Integrace poskytovatelů** | 20+ | Dynamický registr modelů, doba zchlazení poskytovatelů, Codex pro více účtů, analýza kvót Copilota |\n| ⚡ **Výkon** | 15+ | Dvojitá vrstva mezipaměti, mezipaměť výzev, mezipaměť odpovědí, udržování streamování, dávkové API |\n| 🌐 **Ekosystém** | 10+ | WebSocket API, horké opětovné načítání konfigurace, distribuované úložiště konfigurace, komerční režim |\n\n### 🔜 Již brzy\n\n- 🔗 **Integrace OpenCode** — Nativní podpora poskytovatelů pro IDE kódování s AI v OpenCode\n- 🔗 **Integrace TRAE** — Plná podpora vývojového rámce TRAE pro umělou inteligenci\n- 📦 **Dávkové API** — Asynchronní dávkové zpracování hromadných požadavků\n- 🎯 **Směrování na základě tagů** — Směrování požadavků na základě vlastních tagů a metadat\n- 💰 **Strategie nejnižších nákladů** – Automaticky vybere nejlevnějšího dostupného poskytovatele\n\n> 📝 Úplné specifikace funkcí jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobných specifikací)\n\n---\n\n## 👥 Přispěvatelé\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Přispěvatelé](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak přispět\n\n1. Vytvoření forku repozitáře\n2. Vytvořte si vlastní větev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrďte změny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do větve ( `git push origin feature/amazing-feature` )\n5. Otevřít žádost o změny (pull request)\n\nPodrobné pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydání nové verze\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Hvězdná historie\n\n## Hvězdáři v průběhu času\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvězdáři v průběhu času](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## 🙏 Poděkování\n\nZvláštní poděkování patří **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** – původnímu projektu, který inspiroval tento fork. OmniRoute staví na tomto neuvěřitelném základu s dalšími funkcemi, multimodálními API a kompletním přepsáním TypeScriptu.\n\nZvláštní poděkování patří **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – původní implementaci Go, která inspirovala tento JavaScriptový port.\n\n---\n\n## 📄 Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n<div align=\"center\">\n <sub>Vytvořeno s ❤️ pro vývojáře, kteří programují 24 hodin denně, 7 dní v týdnu</sub>\n <br>\n <sub><p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\">omniroute.online</a></p></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "9eb3c2349439e57999804619dfe7658844981a2a": {"t": 1785764462.7234874, "n": 92285, "h": "34425aa96dd72148", "c": "# 🚀 OmniRoute — Bezplatná brána umělé inteligence\n\n### Nikdy nepřestávejte s kódováním. Chytré směrování k **BEZPLATNÝM a levným modelům AI** s automatickým přepínáním mezi záložními systémy.\n\n_Váš univerzální API proxy – jeden endpoint, více než 44 poskytovatelů, nulové výpadky. Nyní s orchestrací agentů **MCP a A2A** ._\n\n**Dokončení chatu • Vkládání • Generování obrázků • Video • Hudba • Audio • Změna pořadí • **Vyhledávání na webu** • MCP server • A2A protokol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n</div>\n<p data-md-type=\"paragraph\"><a href=\"https://www.npmjs.com/package/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/npm/v/omniroute?color=cb3837&amp;logo=npm\" alt=\"verze npm\" data-md-type=\"image\"><a href=\"https://hub.docker.com/r/diegosouzapw/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&amp;logo=docker&amp;color=2496ED\" alt=\"Docker Hub\" data-md-type=\"image\"><a href=\"https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/github/license/diegosouzapw/OmniRoute\" alt=\"Licence\" data-md-type=\"image\"><a href=\"https://omniroute.online\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&amp;logoColor=white\" alt=\"Webové stránky\" data-md-type=\"image\"><a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&amp;logoColor=white\" alt=\"WhatsApp\" data-md-type=\"image\"></p>\n<p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\" data-md-type=\"link\">🌐 Webové stránky</a> • <a href=\"#-quick-start\" data-md-type=\"link\">🚀 Rychlý start</a> • <a href=\"#-key-features\" data-md-type=\"link\">💡 Funkce</a> • <a href=\"#-documentation\" data-md-type=\"link\">📖 Dokumentace</a> • <a href=\"#-pricing-at-a-glance\" data-md-type=\"link\">💰 Ceník</a> • <a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\">💬 WhatsApp</a></p>\n<div data-md-type=\"block_html\"></div>\n\n🌐 **Dostupné v:** 🇺🇸 [Angličtina](README.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [maďarština](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonésie](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nizozemsko](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)\n\n---\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n## 🖼️ Hlavní ovládací panel\n\n<div align=\"center\"> <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"Řídicí panel OmniRoute\" width=\"800\"> </div>\n\n---\n\n## 📸 Náhled řídicího panelu\n\n<details>\n<summary><b>Kliknutím zobrazíte snímky obrazovky z řídicího panelu</b></summary>\n</details>\n\n| Strana | Snímek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelé** | ![Poskytovatelé](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdraví** | ![Zdraví](docs/screenshots/04-health.png) |\n| **Překladatel** | ![Překladatel](docs/screenshots/05-translator.png) |\n| **Nastavení** | ![Nastavení](docs/screenshots/06-settings.png) |\n| **Nástroje CLI** | ![Nástroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly používání** | ![Používání](docs/screenshots/08-usage.png) |\n| **Koncové body** | ![Koncové body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### 🤖 Bezplatný poskytovatel umělé inteligence pro vaše oblíbené programátory\n\n_Připojte libovolný nástroj IDE nebo CLI s umělou inteligencí přes OmniRoute — bezplatnou API bránu pro neomezené kódování._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openclaw/openclaw\"><img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"><br><b>OpenClaw</b></a><br> <sub>⭐ 205 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/HKUDS/nanobot\"><img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"><br><b>NanoBot</b></a><br> <sub>⭐ 20,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/sipeed/picoclaw\"><img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"><br><b>PicoClaw</b></a><br> <sub>⭐ 14,6 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/zeroclaw-labs/zeroclaw\"><img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"><br><b>ZeroClaw</b></a><br> <sub>⭐ 9,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/nearai/ironclaw\"><img src=\"./public/providers/ironclaw.png\" alt=\"Železný dráp\" width=\"48\"><br><b>Železný dráp</b></a><br> <sub>⭐ 2,1 tisíce</sub> </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anomalyco/opencode\"><img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"><br><b>OpenCode</b></a><br> <sub>⭐ 106 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openai/codex\"><img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"><br><b>Codex CLI</b></a><br> <sub>⭐ 60,8 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anthropics/claude-code\"><img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"><br><b>Claude Code</b></a><br> <sub>⭐ 67,3 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/google-gemini/gemini-cli\"><img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"><br> <b>Gemini CLI</b></a><br> <sub>⭐ 94,7 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/Kilo-Org/kilocode\"><img src=\"./public/providers/kilocode.png\" alt=\"Kilo kód\" width=\"48\"><br><b>Kilo kód</b></a><br> <sub>⭐ 15,5 tisíc</sub> </td>\n </tr>\n </table>\n\n<sub>📡 Všichni agenti se připojují přes <code>http://localhost:20128/v1</code> nebo <code>http://cloud.omniroute.online/v1</code> — jedna konfigurace, neomezené modely a kvóty</sub>\n\n---\n\n## 🤔 Proč OmniRoute?\n\n**Přestaňte plýtvat penězi a narážet na limity:**\n\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Kvóta předplatného vyprší každý měsíc\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Limity rychlosti vám zabrání v kódování\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Drahá API (20–50 USD/měsíc na poskytovatele)\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Ruční přepínání mezi poskytovateli\n\n**OmniRoute to řeší:**\n\n- ✅ **Maximalizujte předplatné** – Sledujte kvótu, využijte každou částku před resetováním\n- ✅ **Automatické záložní** – Předplatné → API klíč → Levné → Zdarma, žádné výpadky\n- ✅ **Více účtů** – Round-robin mezi účty u jednotlivých poskytovatelů\n- ✅ **Univerzální** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakýmkoli nástrojem CLI\n\n---\n\n## 📧 Podpora\n\n> 💬 **Přidejte se k naší komunitě!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získejte pomoc, sdílejte tipy a buďte v obraze.\n\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problémy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitní skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Přispívání** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevřete žádost o příspěvek nebo si vyberte `good first issue`\n- **Původní projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### 🐛 Hlásíte chybu?\n\nPři otevírání problému spusťte příkaz system-info a přiložte vygenerovaný soubor:\n\n```bash\nnpm run system-info\n```\n\nTím se vygeneruje soubor `system-info.txt` s verzí Node.js, verzí OmniRoute, podrobnostmi o operačním systému, nainstalovanými nástroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systémovými balíčky – vše, co potřebujeme k rychlé reprodukci vašeho problému. Soubor přiložte přímo k vašemu problému na GitHubu.\n\n---\n\n## 🔄 Jak to funguje\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 Co řeší OmniRoute — 30 skutečných problémů a případů použití\n\n> **Každý vývojář používající nástroje umělé inteligence se s těmito problémy setkává denně.** OmniRoute byl vytvořen tak, aby je všechny vyřešil – od překročení nákladů po regionální bloky, od nefunkčních toků OAuth až po operace s protokoly a sledovatelnost v podniku.\n\n<details>\n<summary><b>💸 1. „Platím si drahé předplatné, ale stále mě ruší limity“</b></summary>\n</details>\n\nVývojáři platí za Claude Pro, Codex Pro nebo GitHub Copilot 20–200 dolarů měsíčně. I při platbě má kvóta strop – 5 hodin používání, týdenní limity nebo limity rychlosti za minutu. Uprostřed kódovací relace poskytovatel přestane reagovat a vývojář ztrácí plynulost a produktivitu.\n\n**Jak to OmniRoute řeší:**\n\n- **Inteligentní čtyřúrovňová záložní služba** – Pokud dojde kvóta předplatného, ​​automaticky se přesměruje na API klíč → Levné → Zdarma bez manuálního zásahu\n- **Sledování kvót v reálném čase** – Zobrazuje spotřebu tokenů v reálném čase s odpočítáváním resetování (5 hodin, denně, týdně)\n- **Podpora více účtů** – Více účtů u jednoho poskytovatele s automatickým přepínáním – když jeden dojde, přepne se na další\n- **Vlastní kombinace** — Přizpůsobitelné záložní řetězce se 6 strategiemi vyvažování (fill-first, round robin, P2C, náhodné, nejméně používané, nákladově optimalizované)\n- **Codex Business Quotas** — Sledování kvót pracovního prostoru firmy/týmu přímo v dashboardu\n\n<details>\n<summary><b>🔌 2. „Potřebuji použít více poskytovatelů, ale každý má jiné API“</b></summary>\n</details>\n\nOpenAI používá jeden formát, Claude (Anthropic) jiný a Gemini ještě třetí. Pokud chce vývojář testovat modely od různých poskytovatelů nebo mezi nimi přecházet, musí překonfigurovat SDK, změnit koncové body a vypořádat se s nekompatibilními formáty. Vlastní poskytovatelé (FriendLI, NIM) mají nestandardní koncové body modelů.\n\n**Jak to OmniRoute řeší:**\n\n- **Sjednocený koncový bod** — Jeden `http://localhost:20128/v1` slouží jako proxy pro všech 67+ poskytovatelů.\n- **Překlad formátu** — Automatický a transparentní: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Sanitizace odpovědí** — Odstraňuje nestandardní pole ( `x_groq` , `usage_breakdown` , `service_tier` ), která porušují OpenAI SDK v1.83+\n- **Normalizace rolí** — Převádí `developer` → `system` pro poskytovatele bez OpenAI; `system` → `user` pro GLM/ERNIE\n- **Extrakce tagů Think** — Extrahuje bloky `<think>` z modelů, jako je DeepSeek R1, do standardizovaného `reasoning_content`\n- **Strukturovaný výstup pro Gemini** — `json_schema` → automatická konverze `responseMimeType` / `responseSchema`\n- **Výchozí hodnota `stream` je `false`** – Odpovídá specifikaci OpenAI, čímž se zabrání neočekávanému SSE v Python/Rust/Go SDK.\n\n<details>\n<summary><b>🌐 3. „Můj poskytovatel AI blokuje můj region/zemi“</b></summary>\n</details>\n\nPoskytovatelé jako OpenAI/Codex blokují přístup z určitých geografických oblastí. Uživatelé se během připojení OAuth a API dostávají k chybám jako `unsupported_country_region_territory` . To je obzvláště frustrující pro vývojáře z rozvojových zemí.\n\n**Jak to OmniRoute řeší:**\n\n- **3úrovňová konfigurace proxy** – Konfigurovatelná proxy na 3 úrovních: globální (veškerý provoz), pro jednotlivé poskytovatele (pouze jeden poskytovatel) a pro jednotlivé připojení/klíč\n- **Barevně kódované odznaky proxy** – Vizuální indikátory: 🟢 globální proxy, 🟡 proxy poskytovatele, 🔵 proxy připojení, vždy zobrazující IP adresu\n- **Výměna tokenů OAuth prostřednictvím proxy** – tok OAuth také prochází přes proxy, čímž se řeší `unsupported_country_region_territory`\n- **Testy připojení přes proxy** – Testy připojení používají nakonfigurovaný proxy (již žádné přímé obcházení)\n- **Podpora SOCKS5** — Plná podpora proxy SOCKS5 pro odchozí směrování\n- **TLS Fingerprint Spoofing** — Otisk prstu TLS podobný prohlížeči pomocí `wreq-js` pro obcházení detekce botů\n- **🔏 Porovnávání otisků prstů v CLI** — Změní pořadí záhlaví a polí v těle serveru tak, aby odpovídala nativním binárním podpisům v CLI, čímž drasticky snižuje riziko nahlašování účtu. IP adresa proxy je zachována — získáte současně stealth **i** maskování IP adresy.\n\n<details>\n<summary><b>🆓 4. „Chci používat umělou inteligenci pro kódování, ale nemám peníze“</b></summary>\n</details>\n\nNe každý si může dovolit zaplatit 20–200 dolarů měsíčně za předplatné AI. Studenti, vývojáři z rozvíjejících se zemí, amatéři a freelanceři potřebují přístup ke kvalitním modelům za nulovou cenu.\n\n**Jak to OmniRoute řeší:**\n\n- **Vestavění poskytovatelé bezplatné úrovně** — Nativní podpora pro 100% bezplatné poskytovatele: iFlow (5 neomezených modelů přes OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezené modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisíc tokenů/měsíc zdarma)\n- **Ollama Cloud** — Cloudově hostované modely Ollama na `api.ollama.com` s bezplatnou úrovní „Light usage“; použijte prefix `ollamacloud/<model>`\n- **Kombinace pouze zdarma** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/měsíc s nulovými prostoji\n- **NVIDIA NIM Free Access** — ~40 RPM developerský přístup k více než 70 modelům na build.nvidia.com (přechod z kreditů na čisté limity rychlosti)\n- **Strategie optimalizace nákladů** – Strategie směrování, která automaticky vybere nejlevnějšího dostupného poskytovatele\n\n<details>\n<summary><b>🔒 5. „Potřebuji chránit svou bránu umělé inteligence před neoprávněným přístupem“</b></summary>\n</details>\n\nPři zpřístupnění brány umělé inteligence síti (LAN, VPS, Docker) může kdokoli s adresou spotřebovat tokeny/kvótu vývojáře. Bez ochrany jsou API zranitelná vůči zneužití, prompt injection a dalšímu zneužití.\n\n**Jak to OmniRoute řeší:**\n\n- **Správa klíčů API** – generování, rotace a vymezování rozsahu pro každého poskytovatele s vyhrazenou stránkou `/dashboard/api-manager`\n- **Oprávnění na úrovni modelu** – Omezení klíčů API na konkrétní modely ( `openai/*` , zástupné znaky) pomocí přepínače Povolit vše/Omezit\n- **Ochrana koncových bodů API** – Vyžaduje klíč pro `/v1/models` a blokuje konkrétní poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** — Všechny trasy dashboardu chráněné middlewarem `withAuth` + tokeny CSRF\n- **Omezovač rychlosti** — Omezování rychlosti na IP s konfigurovatelnými okny\n- **Filtrování IP adres** — Seznam povolených/blokovaných adres pro řízení přístupu\n- **Ochrana proti vkládání výzev** – Sanitizace proti škodlivým vzorcům výzev\n- **Šifrování AES-256-GCM** – přihlašovací údaje jsou v klidovém stavu šifrovány\n\n<details>\n<summary><b>🛑 6. „Můj poskytovatel selhal a já ztratil/a programovací tok“</b></summary>\n</details>\n\nPoskytovatelé umělé inteligence se mohou stát nestabilními, vracet chyby 5xx nebo dosáhnout dočasných limitů rychlosti. Pokud je vývojář závislý na jediném poskytovateli, je jeho práce přerušena. Bez jističů může opakované pokusy vést k pádu aplikace.\n\n**Jak to OmniRoute řeší:**\n\n- **Jistič pro každý model** – Automatické otevírání/zavírání s konfigurovatelnými prahovými hodnotami a dobou ochlazování (Zavřeno/Otevřeno/Poloviční otevření), rozsah definovaný pro každý model, aby se zabránilo kaskádování bloků\n- **Exponenciální odklad** — Progresivní zpoždění opakování\n- **Anti-Thundering Herd** — ochrana Mutex + semafor proti souběžným bouřím s opakovanými pokusy\n- **Kombinované záložní řetězce** – Pokud primární poskytovatel selže, automaticky se propadne řetězcem bez zásahu.\n- **Kombinovaný jistič** – Automaticky deaktivuje selhávajícího poskytovatele v rámci kombinovaného řetězce\n- **Dashboard stavu** — Monitorování provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti, latence p50/p95/p99\n\n<details>\n<summary><b>🔧 7. „Konfigurace každého nástroje umělé inteligence je zdlouhavá a opakující se“</b></summary>\n</details>\n\nVývojáři používají Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Každý nástroj potřebuje jinou konfiguraci (API endpoint, klíč, model). Překonfigurování při změně poskytovatele nebo modelu je ztráta času.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel nástrojů CLI** — Vyhrazená stránka s nastavením jedním kliknutím pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generátor konfigurace GitHub Copilot** – Generuje `chatLanguageModels.json` pro VS Code s hromadným výběrem modelu\n- **Průvodce zaváděním** – 4krokové nastavení pro začínající uživatele\n- **Jeden koncový bod, všechny modely** – jednou nakonfigurujte `http://localhost:20128/v1` a získejte přístup k více než 44 poskytovatelům\n\n<details>\n<summary><b>🔑 8. „Správa OAuth tokenů od více poskytovatelů je peklo“</b></summary>\n</details>\n\nClaude Code, Codex, Gemini CLI, Copilot – všechny používají OAuth 2.0 s tokeny s vypršením platnosti. Vývojáři se musí neustále znovu autentizovat, řešit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdálených serverech. Obzvláště problematický je OAuth v LAN/VPS.\n\n**Jak to OmniRoute řeší:**\n\n- **Automatická aktualizace tokenů** – Tokeny OAuth se obnovují na pozadí před vypršením platnosti.\n- **Vestavěný OAuth 2.0 (PKCE)** – Automatický tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** — Více účtů na poskytovatele prostřednictvím extrakce tokenů JWT/ID\n- **OAuth LAN/Remote Fix** — Detekce privátní IP adresy pro `redirect_uri` + manuální režim URL pro vzdálené servery\n- **OAuth Behind Nginx** — Používá `window.location.origin` pro kompatibilitu s reverzní proxy\n- **Průvodce vzdáleným OAuth** – Podrobný návod k přihlašovacím údajům Google Cloud na VPS/Dockeru\n\n<details>\n<summary><b>📊 9. „Nevím, kolik utrácím ani kde“</b></summary>\n</details>\n\nVývojáři používají více placených poskytovatelů, ale nemají jednotný přehled o výdajích. Každý poskytovatel má svůj vlastní fakturační panel, ale neexistuje žádný konsolidovaný přehled. Mohou se hromadit neočekávané náklady.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard pro analýzu nákladů** – Sledování nákladů na token a správa rozpočtu pro každého poskytovatele\n- **Rozpočtové limity na úroveň** – Strop výdajů na úroveň, který spouští automatický záložní režim\n- **Konfigurace cen podle modelu** – Konfigurovatelné ceny podle modelu\n- **Statistiky použití pro každý klíč API** — Počet požadavků a časové razítko posledního použití pro každý klíč\n- **Analytický panel** – Statistické karty, graf využití modelu, tabulka poskytovatelů s mírou úspěšnosti a latencí\n\n<details>\n<summary><b>🐛 10. „Nedokážu diagnostikovat chyby a problémy ve volání umělé inteligence.“</b></summary>\n</details>\n\nKdyž volání selže, vývojář neví, zda se jednalo o limit rychlosti, vypršelý token, špatný formát nebo chybu poskytovatele. Fragmentované protokoly napříč různými terminály. Bez sledovatelnosti je ladění metodou pokus-omyl.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel jednotných protokolů** – 4 karty: Protokoly požadavků, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlížeč protokolů konzole** — Prohlížeč protokolů v reálném čase ve stylu terminálu s barevně kódovanými úrovněmi, automatickým posouváním, vyhledáváním a filtrováním\n- **Protokoly proxy SQLite** – trvalé protokoly, které přežijí restart serveru\n- **Překladačské hřiště** — 4 režimy ladění: Hřiště (překlad formátu), Tester chatu (okružní), Testovací stůl (dávkový), Živý monitor (v reálném čase)\n- **Telemetrie požadavků** — latence p50/p95/p99 + trasování X-Request-Id\n- **Souborové protokolování s rotací** – Konzolový interceptor zachycuje vše do protokolu JSON s rotací na základě velikosti\n- **Zpráva o systémových informacích** — příkaz `npm run system-info` vygeneruje `system-info.txt` s kompletním popisem vašeho prostředí (verze uzlu, verze OmniRoute, operační systém, nástroje CLI, stav Dockeru/PM2). Přiložte jej při hlášení problémů pro okamžité třídění.\n\n<details>\n<summary><b>🏗️ 11. „Nasazení a údržba brány je složitá“</b></summary>\n</details>\n\nInstalace, konfigurace a údržba AI proxy v různých prostředích (lokální, VPS, Docker, cloud) je pracná. Problémy, jako jsou pevně zakódované cesty, `EACCES` u adresářů, konflikty portů a multiplatformní sestavení, přispívají k obtížím.\n\n**Jak to OmniRoute řeší:**\n\n- **npm globální instalace** — `npm install -g omniroute && omniroute` — hotovo\n- **Docker Multi-Platform** — AMD64 + nativní ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** — `base` (bez nástrojů CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopová aplikace Electron** — Nativní aplikace pro Windows/macOS/Linux se systémovou lištou, automatickým spuštěním a offline režimem\n- **Režim rozdělených portů** – API a řídicí panel na samostatných portech pro pokročilé scénáře (reverzní proxy, síťování kontejnerů)\n- **Cloud Sync** – Konfigurace synchronizace mezi zařízeními pomocí Cloudflare Workers\n- **Zálohy databází** — Automatické zálohování, obnovení, export a import všech nastavení\n\n<details>\n<summary><b>🌍 12. „Rozhraní je pouze v angličtině a můj tým nemluví anglicky“</b></summary>\n</details>\n\nTýmy v neanglicky mluvících zemích, zejména v Latinské Americe, Asii a Evropě, se potýkají s rozhraními pouze v angličtině. Jazykové bariéry snižují míru přijetí a zvyšují chyby v konfiguraci.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard i18n — 30 jazyků** — Všech 500+ kláves je přeloženo včetně arabštiny, bulharštiny, dánštiny, němčiny, španělštiny, finštiny, francouzštiny, hebrejštiny, hindštiny, maďarštiny, indonéštiny, italštiny, japonštiny, korejštiny, malajštiny, holandštiny, norštiny, polštiny, portugalštiny (PT/BR), rumunštiny, ruštiny, slovenštiny, švédštiny, thajštiny, ukrajinštiny, vietnamštiny, čínštiny, filipínštiny a angličtiny\n- **Podpora RTL** – Podpora psaní zprava doleva pro arabštinu a hebrejštinu\n- **Vícejazyčné soubory README** — 30 kompletních překladů dokumentace\n- **Výběr jazyka** — Ikona glóbu v záhlaví pro přepínání v reálném čase\n\n<details>\n<summary><b>🔄 13. „Potřebuji víc než jen chat – potřebuji vložené soubory, obrázky, zvuk.“</b></summary>\n</details>\n\nUmělá inteligence není jen dokončování chatu. Vývojáři potřebují generovat obrázky, přepisovat zvuk, vytvářet embeddedy pro RAG, měnit pořadí dokumentů a moderovat obsah. Každé API má jiný koncový bod a formát.\n\n**Jak to OmniRoute řeší:**\n\n- **Vkládání** — `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generování obrázků** — `/v1/images/generations` s 10 poskytovateli a více než 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Převod textu na video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Převod textu na hudbu** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Přepis zvuku** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Převod textu na řeč** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a další stávající poskytovatelé\n- **Moderování** — `/v1/moderations` — Kontroly bezpečnosti obsahu\n- **Změna pořadí** — `/v1/rerank` — Změna pořadí relevance dokumentu\n- **Responses API** — Plná podpora `/v1/responses` pro Codex\n\n<details>\n<summary><b>🧪 14. „Nemám způsob, jak testovat a porovnávat kvalitu napříč modely.“</b></summary>\n</details>\n\nVývojáři chtějí vědět, který model je pro jejich případ použití nejlepší – kód, překlad, uvažování – ale ruční porovnávání je pomalé. Neexistují žádné integrované nástroje pro vyhodnocování.\n\n**Jak to OmniRoute řeší:**\n\n- **Hodnocení LLM** — Testování Golden setu s 10 předinstalovanými případy zahrnujícími pozdravy, matematiku, geografii, generování kódu, dodržování JSON, překlad, markdown, odmítnutí bezpečnostních požadavků\n- **4 strategie shody** — `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovací lavice pro překladatelské hřiště** — Dávkové testování s více vstupy a očekávanými výstupy, porovnání napříč poskytovateli\n- **Tester chatu** — Kompletní okružní cesta s vizuálním vykreslováním odpovědí\n- **Živý monitor** — Stream všech požadavků procházejících proxy serverem v reálném čase\n\n<details>\n<summary><b>📈 15. „Potřebuji škálovat bez ztráty výkonu“</b></summary>\n</details>\n\nS rostoucím objemem požadavků generují stejné otázky bez ukládání do mezipaměti duplicitní náklady. Bez idempotence duplicitní požadavky plýtvají zpracováním. Je nutné dodržovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute řeší:**\n\n- **Sémantická mezipaměť** — Dvouvrstvá mezipaměť (signatura + sémantika) snižuje náklady a latenci\n- **Idempotence požadavku** — 5s deduplikační okno pro identické požadavky\n- **Detekce limitu rychlosti** – sledování otáček za minutu (RPM), minimální mezera a maximální souběžné sledování pro každého poskytovatele\n- **Upravitelné limity rychlosti** — Konfigurovatelné výchozí hodnoty v Nastavení → Odolnost s perzistencí\n- **Mezipaměť pro ověření klíčů API** — třívrstvá mezipaměť pro výkon produkčního prostředí\n- **Dashboard s telemetrií** – latence p50/p95/p99, statistiky mezipaměti, dostupnost\n\n<details>\n<summary><b>🤖 16. „Chci mít chování modelů globálně pod kontrolou“</b></summary>\n</details>\n\nVývojáři, kteří chtějí všechny odpovědi v určitém jazyce, se specifickým tónem nebo chtějí omezit tokeny pro uvažování. Konfigurace této funkce v každém nástroji/požadavku je nepraktická.\n\n**Jak to OmniRoute řeší:**\n\n- **Vložení systémového prompt** – Globální prompt aplikovaný na všechny požadavky\n- **Validace rozpočtu Thinking** — Řízení alokace tokenů na požadavek (průchozí, automatické, vlastní, adaptivní)\n- **6 strategií směrování** – Globální strategie, které určují, jak jsou požadavky distribuovány\n- **Směrovač se zástupnými znaky** — vzory `provider/*` dynamicky směrují k libovolnému poskytovateli\n- **Přepínání povolení/zakázání kombinací** – Přepínání kombinací přímo z řídicího panelu\n- **Přepínání poskytovatele** – Povolení/zakázání všech připojení pro poskytovatele jedním kliknutím\n- **Blokovaní poskytovatelé** – Vyloučení konkrétních poskytovatelů ze seznamu `/v1/models`\n\n<details>\n<summary><b>🧰 17. „Potřebuji nástroje MCP jako prvotřídní produktové funkce.“</b></summary>\n</details>\n\nMnoho bran umělé inteligence odhaluje MCP pouze jako skrytý implementační detail. Týmy potřebují viditelnou a spravovatelnou operační vrstvu.\n\n**Jak to OmniRoute řeší:**\n\n- MCP se zobrazuje v navigaci na řídicím panelu a na kartě protokolu koncového bodu.\n- Vyhrazená stránka pro správu MCP s procesy, nástroji, rozsahy a auditem\n- Vestavěný rychlý start pro `omniroute --mcp` a onboarding klienta\n\n<details>\n<summary><b>🧠 18. „Potřebuji orchestraci A2A se synchronizací a cestami úloh streamu.“</b></summary>\n</details>\n\nPracovní postupy agentů vyžadují jak přímé odpovědi, tak dlouhodobé streamované provádění s kontrolou životního cyklu.\n\n**Jak to OmniRoute řeší:**\n\n- Koncový bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamování SSE s šířením stavu terminálu\n- Rozhraní API životního cyklu úloh pro `tasks/get` a `tasks/cancel`\n\n<details>\n<summary><b>🛰️ 19. „Potřebuji skutečný stav procesu MCP, ne odhadovaný stav.“</b></summary>\n</details>\n\nProvozní týmy potřebují vědět, zda je MCP skutečně aktivní, nejen zda je API dosažitelné.\n\n**Jak to OmniRoute řeší:**\n\n- Soubor běhového heartbeatu s PID, časovými razítky, transportem, počtem nástrojů a režimem rozsahu\n- API stavu MCP kombinující prezenční signál a nedávnou aktivitu\n- Karty stavu uživatelského rozhraní pro zobrazení aktuálnosti procesů/provozuschopnosti/prezenčního signálu\n\n<details>\n<summary><b>📋 20. „Potřebuji auditovatelné provedení nástroje MCP“</b></summary>\n</details>\n\nKdyž nástroje mění konfiguraci nebo spouštějí operační akce, týmy potřebují forenzní sledovatelnost.\n\n**Jak to OmniRoute řeší:**\n\n- Protokolování auditu pro volání nástrojů MCP s podporou SQLite\n- Filtruje podle nástroje, úspěchu/neúspěchu, klíče API a stránkování\n- Tabulka auditu dashboardu + koncové body statistik pro automatizaci\n\n<details>\n<summary><b>🔐 21. „Potřebuji omezená oprávnění MCP pro každou integraci.“</b></summary>\n</details>\n\nRůzní klienti by měli mít přístup ke kategoriím nástrojů s nejnižšími oprávněními.\n\n**Jak to OmniRoute řeší:**\n\n- 9 detailních MCP sond pro kontrolovaný přístup k nástrojům\n- Vynucení rozsahu a viditelnost v uživatelském rozhraní správy MCP\n- Bezpečná výchozí poloha pro provozní nástroje\n\n<details>\n<summary><b>⚙️ 22. „Potřebuji provozní kontroly bez nutnosti přesouvání“</b></summary>\n</details>\n\nTýmy potřebují rychlé změny v běhovém prostředí během incidentů nebo nákladových událostí.\n\n**Jak to OmniRoute řeší:**\n\n- Přepněte aktivaci komba přímo z řídicího panelu MCP\n- Používejte profily odolnosti z předdefinovaných balíčků zásad\n- Resetujte stav jističe ze stejného ovládacího panelu\n\n<details>\n<summary><b>🔄 23. „Potřebuji živý přehled o životním cyklu úkolů A2A a jejich zrušení.“</b></summary>\n</details>\n\nBez přehledu o životním cyklu je obtížné třídit incidenty úkolů.\n\n**Jak to OmniRoute řeší:**\n\n- Výpis/filtrování úkolů podle státu/dovednosti s stránkováním\n- Podrobný přehled metadat úloh, událostí a artefaktů\n- Koncový bod zrušení úlohy a akce uživatelského rozhraní s potvrzením\n\n<details>\n<summary><b>🌊 24. „Potřebuji metriky aktivního streamu pro A2A zátěž“</b></summary>\n</details>\n\nStreamovací pracovní postupy vyžadují provozní přehled o souběžnosti a živých připojeních.\n\n**Jak to OmniRoute řeší:**\n\n- Čítače aktivních streamů integrované do stavu A2A\n- Časové razítko posledního úkolu a počty pro jednotlivé stavy\n- Karty A2A dashboardu pro monitorování provozu v reálném čase\n\n<details>\n<summary><b>🪪 25. „Potřebuji standardní vyhledávání agentů pro klienty“</b></summary>\n</details>\n\nExterní klienti a orchestratoři potřebují pro onboarding strojově čitelná metadata.\n\n**Jak to OmniRoute řeší:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazené v uživatelském rozhraní pro správu\n- API pro stav A2A zahrnuje metadata pro zjišťování pro automatizaci\n\n<details>\n<summary><b>🧭 26. „Potřebuji v uživatelském rozhraní produktu zjistitelnost protokolu.“</b></summary>\n</details>\n\nPokud uživatelé nemohou objevit protokolové povrchy, kvalita přijetí a podpory klesá.\n\n**Jak to OmniRoute řeší:**\n\n- Stránka Konsolidované **koncové body** s kartami pro koncové body Proxy, MCP, A2A a API\n- Přepínání stavu inline služby (Online/Offline) pro MCP a A2A\n- Odkazy z přehledu na vyhrazené karty pro správu\n\n<details>\n<summary><b>🧪 27. „Potřebuji komplexní ověření protokolu se skutečnými klienty.“</b></summary>\n</details>\n\nSimulované testy nestačí k ověření kompatibility protokolu před vydáním.\n\n**Jak to OmniRoute řeší:**\n\n- Sada E2E, která spouští aplikaci a používá skutečný transport klienta MCP SDK.\n- Klientské testy A2A pro toky zjišťování, odesílání, streamování, načítání a zrušení\n- Křížová kontrola tvrzení oproti API pro audit MCP a úkoly A2A\n\n<details>\n<summary><b>📡 28. „Potřebuji jednotnou pozorovatelnost napříč všemi rozhraními“</b></summary>\n</details>\n\nRozdělení pozorovatelnosti podle protokolu vytváří slepá místa a delší MTTR.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocené dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie požadavků napříč vrstvami OpenAI, MCP a A2A\n- Provozní API pro stav a automatizaci\n\n<details>\n<summary><b>💼 29. „Potřebuji jeden runtime pro proxy + nástroje + orchestraci agentů“</b></summary>\n</details>\n\nSpouštění mnoha samostatných služeb zvyšuje provozní náklady a počet poruch.\n\n**Jak to OmniRoute řeší:**\n\n- Proxy, MCP server a A2A server kompatibilní s OpenAI v jednom balíčku\n- Sdílené ověřování, odolnost, úložiště dat a pozorovatelnost\n- Konzistentní model politik napříč všemi interakčními plochami\n\n<details>\n<summary><b>🚀 30. „Potřebuji agentské pracovní postupy bez slepení kódu.“</b></summary>\n</details>\n\nTýmy ztrácejí rychlost při spojování více ad-hoc služeb a skriptů.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocená strategie koncových bodů pro klienty a agenty\n- Vestavěná uživatelská rozhraní pro správu protokolů a cesty pro ověřování kouře\n- Základy připravené pro produkční prostředí (zabezpečení, protokolování, odolnost, zálohování)\n\n### Příklady herních plánů (integrované případy užití)\n\n**Příručka A: Maximalizace placeného předplatného + levné zálohování**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Příručka B: Kódovací stack s nulovými náklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Příručka C: Nonstop záložní řetězec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Příručka D: Operace agentů s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Začněte zdarma — Nulové náklady na konfiguraci\n\n> Nastavte si kódování s umělou inteligencí během několika minut za **0 $/měsíc** . Propojte tyto bezplatné účty a využijte vestavěnou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelé odemčeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Připojení **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 – **neomezeně** |\n| 2 | Připojení k **iFlow** (Google OAuth) | kimi-k2-myšlení, qwen3-coder-plus, deepseek-r1... — **neomezeně** |\n| 3 | Připojení **Qwen** (kód zařízení) | qwen3-coder-plus, qwen3-coder-flash... — **neomezeně** |\n| 4 | Připojení **rozhraní příkazového řádku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180 000 GBP/měsíc zdarma** |\n| 5 | `/dashboard/combos` → Šablona **Free Stack (0 $)** | Automatické zařazení všech bezplatných poskytovatelů do routingu |\n\n**V libovolném IDE/CLI naveďte:** `http://localhost:20128/v1` · Klíč API: `any-string` · Hotovo.\n\n> **Volitelné doplňkové krytí (také zdarma):** Groq API klíč (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelů), Cerebras (1 milion tok/den).\n\n## ⚡ Rychlý start\n\n### 1) Nainstalujte a spusťte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uživatelé pnpm:** Po instalaci spusťte `pnpm approve-builds -g` , abyste povolili nativní skripty pro sestavení vyžadované programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard se otevírá na `http://localhost:20128` a základní URL API je `http://localhost:20128/v1` .\n\n| Příkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuštění serveru ( `PORT=20128` , API a dashboard na stejném portu) |\n| `omniroute --port 3000` | Nastavte kanonický/API port na 3000 |\n| `omniroute --mcp` | Spuštění MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevírat prohlížeč automaticky |\n| `omniroute --help` | Zobrazit nápovědu |\n\nVolitelný režim s rozděleným portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Připojte poskytovatele a vytvořte si klíč API\n\n1. Otevřete Dashboard → `Providers` a připojte alespoň jednoho poskytovatele (klíč OAuth nebo API).\n2. Otevřete Dashboard → `Endpoints` a vytvořte API klíč.\n3. (Volitelné) Otevřete Dashboard → `Combos` a nastavte záložní řetězec.\n\n### 3) Nasměrujte svůj kódovací nástroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilními s OpenAI.\n\n### 4) Povolení a ověření protokolů (v2.0)\n\n**MCP (pro operace řízené nástroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak připojte svého MCP klienta přes `stdio` a otestujte nástroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovní postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ověřte vše od začátku do konce (doporučeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ověřuje skutečné toky klientů MCP a A2A v porovnání se spuštěnou aplikací.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## 🐳 Docker\n\nOmniRoute je k dispozici jako veřejný obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlý běh:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostředí:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Používání Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | Štítek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovější stabilní verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuální verze |\n\n---\n\n## 🖥️ Desktopová aplikace – offline a vždy zapnutá\n\n> 🆕 **NOVINKA!** OmniRoute je nyní k dispozici jako **nativní desktopová aplikace** pro Windows, macOS a Linux.\n\nSpusťte OmniRoute jako samostatnou desktopovou aplikaci – pro lokální modely není potřeba žádný terminál, prohlížeč ani internet. Aplikace založená na platformě Electron obsahuje:\n\n- 🖥️ **Nativní okno** — Vyhrazené okno aplikace s integrací do systémové lišty\n- 🔄 **Automatické spuštění** — Spuštění OmniRoute po přihlášení do systému\n- 🔔 **Nativní oznámení** – Získejte upozornění na vyčerpání kvóty nebo problémy s poskytovateli\n- ⚡ **Instalace jedním kliknutím** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline režim** — Funguje plně offline s přiloženým serverem\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systémový zásobník\n\nPo minimalizaci se OmniRoute nachází v systémové liště a nabízí rychlé akce:\n\n- Otevřít řídicí panel\n- Změnit port serveru\n- Ukončit aplikaci\n\n📖 Úplná dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Přehled cen\n\n| Úroveň | Poskytovatel | Náklady | Obnovení kvóty | Nejlepší pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **💳 PŘEDPLATNÉ** | Claude Code (profesionál) | 20 dolarů měsíčně | 5 hodin + týdně | Již přihlášen/a k odběru |\n| Kodex (Plus/Pro) | 20–200 USD/měsíc | 5 hodin + týdně | Uživatelé OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisíc měsíčně + 1 tisíc denně | Každý! |\n| GitHub Copilot | 10–19 USD/měsíc | Měsíční | Uživatelé GitHubu |\n| **🔑 KLÍČ API** | NVIDIA NIM | **ZDARMA** (vývoj navždy) | ~40 ot./min | 70+ otevřených modelů |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší na světě |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisíc otáček za minutu | Ultrarychlá lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | Žádný | Nejlepší zdůvodnění ceny a kvality |\n| xAI Grok-4 Rychlý | **0,20/0,50 USD za 1 milion** 🆕 | Žádný | Nejrychlejší + volání nástroje, ultranízké |\n| xAI Grok-4 (standardní) | 0,20/1,50 USD za 1 milion 🆕 | Žádný | Vlajková loď Reasoning od xAI |\n| Mistral | Zkušební verze zdarma + placené | Omezená sazba | Evropská umělá inteligence |\n| OpenRouter | Platba za použití | Žádný | Více než 100 modelů agregováno. |\n| **💰 LEVNÉ** | GLM-5 (přes Z.AI) 🆕 | 0,5 USD/1 milion | Denně v 10:00 | Výstup 128 tisíc obrazových bodů, nejnovější vlajková loď |\n| GLM-4.7 | 0,6 USD/1 milion | Denně v 10:00 | Záloha rozpočtu |\n| MiniMax M2.5 🆕 | Vstup 0,3 USD/1 milion | 5hodinové válcování | Úvaha + agentní úkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinové válcování | Nejlevnější varianta |\n| Kimi K2.5 (Moonshot API) 🆕 | Platba za použití | Žádný | Přímý přístup k Moonshot API |\n| Kimi K2 | 9 dolarů měsíčně bez závazků | 10 milionů tokenů/měsíc | Předvídatelné náklady |\n| **🆓 ZDARMA** | iFlow | **0 dolarů** | Neomezený | 5 modelů neomezeně |\n| Qwen | **0 dolarů** | Neomezený | 4 modely neomezeně |\n| Kiro | **0 dolarů** | Neomezený | Claude Sonnet/Haiku (tvorce AWS) |\n\n> 🆕 **Přidány nové modely (březen 2026):** řada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkováno na 1143 ms – o 30 % rychlejší než Gemini 2.5 Flash), GLM-5 přes Z.AI s výstupem 128K, uvažování MiniMax M2.5, aktualizované ceny DeepSeek V3.2, Kimi K2.5 přes Moonshot Direct API.\n\n**💡 Kombinovaný balík za 0 $ — Kompletní bezplatná instalace:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\niFlow (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Nulové náklady. Nikdy nepřestávejte s kódováním.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a všechny záložní režimy se provede automaticky – žádné ruční přepínání.\n\n---\n\n---\n\n## 🆓 Bezplatné modely – Co skutečně získáte\n\n> Všechny níže uvedené modely jsou **100% zdarma a nevyžadují žádnou kreditní kartu** . OmniRoute mezi nimi automaticky propojí trasy, když dojde jedna kvóta – zkombinujte je všechny a získejte tak nerozlučnou kombinaci za 0 dolarů.\n\n### 🔵 CLAUDE MODELS (přes Kiro — AWS Builder ID)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-opus-4.6` | `kr/` | **Neomezený** | Nejnovější opus od Kira |\n\n### 🟢 MODELY IFLOW (Bezplatné OAuth — bez nutnosti platit kreditní kartou)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-plus` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `deepseek-r1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `minimax-m2.1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `kimi-k2` | `if/` | **Neomezený** | Žádný hlášený strop |\n\n### 🟡 MODELY QWEN (Ověření kódu zařízení)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-next` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `vision-model` | `qw/` | **Neomezený** | Multimodální (obrázky) |\n\n### 🟣 Rozhraní GEMINI CLI (Google OAuth)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisíc tok/měsíc** + 1 tisíc/den | Měsíční reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisíc měsíčně (sdílený bazén) | Vysoká kvalita |\n\n### ⚫ NVIDIA NIM (Bezplatný klíč API — build.nvidia.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vývojář) | Žádný limit tokenů | **~40 ot./min** | Více než 70 modelů; přechod na čisté limity sazeb v polovině roku 2025 |\n\nOblíbené bezplatné modely: `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`\n\n### ⚪ CEREBRAS (Bezplatný klíč API — inference.cerebras.ai)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenů/den** | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší inference LLM na světě; denně se resetuje |\n\nDostupné zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Bezplatný API klíč — console.groq.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisíc otáček za minutu** | 30 ot./min na model | Žádná kreditní karta; limit 429, neúčtováno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **💡 Ultimátní bezplatný zásobník:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> → iFlow (5 models, unlimited)\n> → Qwen (4 models, unlimited)\n> → Gemini CLI (180K/mo)\n> → Cerebras (1M tok/day)\n> → Groq (14.4K req/day)\n> → NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a už nikdy nebudete platit za umělou inteligenci.\n\n## 🎙️ Kombinovaná transkripce zdarma\n\n> Přepisujte libovolné audio/video za **0 $** – Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako záložní nástroj, Groq Whisper jako neomezená nouzová záloha.\n\n| Poskytovatel | Bezplatné kredity | Nejlepší model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| 🟢 **Deepgram** | **200 dolarů zdarma** (registrace) | `nova-3` — nejvyšší přesnost, více než 30 jazyků | Žádný limit RPM pro kredity zdarma |\n| 🔵 **AssemblyAI** | **50 dolarů zdarma** (registrace) | `universal-3-pro` — kapitoly, sentiment, osobní údaje | Žádný limit RPM pro kredity zdarma |\n| 🔴 **Groq** | **Navždy zdarma** | `whisper-large-v3` — OpenAI Šepot | 30 ot./min (omezená rychlost) |\n\n**Navrhovaná kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nPak v `/dashboard/media` → záložka **Přepis** : nahrajte libovolný zvukový nebo video soubor → vyberte kombinovaný koncový bod → získejte přepis v podporovaných formátech.\n\n## 💡 Klíčové vlastnosti\n\nOmniRoute v2.0 je navržen jako operační platforma, nikoli pouze jako proxy pro relé.\n\n### 🤖 Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dělá |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **MCP Server (16 nástrojů)** | Nástroje IDE/agent prostřednictvím 3 transportů: stdio, SSE ( `/api/mcp/sse` ), Streamovatelný HTTP ( `/api/mcp/stream` ) |\n| 🤝 **A2A server (JSON-RPC + SSE)** | Spouštění úloh mezi agenty se synchronizací a streamováním |\n| 🧭 **Konsolidovaná stránka koncových bodů** | Stránka pro správu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| 🎚️ **Přepínače pro povolení/zakázání služby** | Přepínače ZAP/VYP pro MCP a A2A s trvalým nastavením (výchozí: VYP) |\n| 🛰️ **Srdeční tep za běhu MCP** | Skutečný stav procesu (pid, doba provozuschopnosti, stáří heartbeatu, transport, režim rozsahu) |\n| 📋 **Auditní záznam MCP** | Filtrovatelné protokoly auditu s hodnocením úspěchu/neúspěchu a klíčovým přiřazením |\n| 🔐 **Vynucování rozsahu MCP** | 9 podrobných oprávnění pro řízený přístup k nástrojům |\n| 📡 **Správa životního cyklu úkolů A2A** | Seznam/filtrování úloh, kontrola událostí/artefaktů, zrušení spuštěných úloh |\n| 📋 **Objevení karty agenta** | `/.well-known/agent.json` pro automatické vyhledávání klientů |\n| 🧪 **Testovací postroj Protocol E2E** | Skutečné MCP SDK + toky klientů A2A v `test:protocols:e2e` |\n| ⚙️ **Provozní kontroly** | Kombinace přepínačů, použití profilů odolnosti, resetování jističů z jednoho ovládacího panelu |\n\n### 🧠 Směrování a inteligence\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| 🎯 **Inteligentní čtyřúrovňový záložní systém** | Automatická trasa: Předplatné → API klíč → Levné → Zdarma |\n| 📊 **Sledování kvót v reálném čase** | Počet tokenů v reálném čase + odpočet resetování pro každého poskytovatele |\n| 🔄 **Překlad formátu** | OpenAI ↔ Claude ↔ Gemini ↔ Odpovědi s konverzemi bezpečnými pro schéma |\n| 👥 **Podpora více účtů** | Více účtů na poskytovatele s inteligentním výběrem |\n| 🔄 **Automatická aktualizace tokenů** | Tokeny OAuth se automaticky obnovují při opakovaném pokusu. |\n| 🎨 **Vlastní kombinace** | 6 vyvažovacích strategií + řízení záložního řetězce |\n| 🌐 **Směrovač se zástupnými znaky** | dynamické směrování `provider/*` |\n| 🧠 **Přemýšlení o rozpočtových kontrolách** | Limity pro průchozí, automatické, vlastní a adaptivní uvažování |\n| 🔀 **Aliasy modelů** | Vestavěné + vlastní aliasování modelů a bezpečnost migrace |\n| ⚡ **Degradace pozadí** | Směrujte úlohy na pozadí s nízkou prioritou na levnější modely |\n| 🧪 **Chytré směrování s ohledem na úkoly** | Automatický výběr modelu podle typu obsahu (kódování/vize/analýza/sumarizace) |\n| 💬 **Vstřikování do systému** | Globální kontroly chování uplatňované konzistentně |\n| 📄 **Kompatibilita API pro odpovědi** | Plná podpora `/v1/responses` pro Codex a pokročilé agentické pracovní postupy |\n\n### 🎵 Multimodální API\n\n| Funkce | Co to dělá |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Generování obrázků** | `/v1/images/generations` s cloudovým a lokálním backendem |\n| 📐 **Vložení** | `/v1/embeddings` pro vyhledávání a RAG pipelines |\n| 🎤 **Přepis zvuku** | `/v1/audio/transcriptions` (Whisper a další poskytovatelé) |\n| 🔊 **Převod textu na řeč** | `/v1/audio/speech` (více enginů/poskytovatelů) |\n| 🎬 **Generování videa** | `/v1/videos/generations` (pracovní postupy ComfyUI + SD WebUI) |\n| 🎵 **Hudební generace** | `/v1/music/generations` (pracovní postupy ComfyUI) |\n| 🛡️ **Moderování** | Bezpečnostní kontroly `/v1/moderations` |\n| 🔀 **Změna pořadí** | `/v1/rerank` pro hodnocení relevance |\n| 🔍 **Vyhledávání na webu** 🆕 | `/v1/search` — 5 poskytovatelů (Serper, Brave, Perplexity, Exa, Tavily), více než 6 500 zdarma/měsíc, automatické přepnutí na záložní systém, mezipaměť |\n\n### 🛡️ Odolnost, bezpečnost a správa věcí veřejných\n\n| Funkce | Co to dělá |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| 🔌 **Jističe** | Vypnutí/obnovení pro každý model s ovládáním prahových hodnot |\n| 🎯 **Modely s ohledem na koncové body** | Vlastní modely deklarují podporované koncové body + formát API |\n| 🛡️ **Stádo proti hromům** | Ochrana mutexu a semaforu při událostech opakování/rychlosti |\n| 🧠 **Sémantická + podpisová mezipaměť** | Snížení nákladů/latence díky dvěma vrstvám mezipaměti |\n| ⚡ **Žádost o idempotenci** | Okno ochrany proti duplikacím |\n| 🔒 **Falšování otisků prstů pomocí TLS** | Otisk TLS podobný prohlížeči – **snižuje detekci botů a nahlašování účtů** |\n| 🔏 **Porovnávání otisků prstů v CLI** | Shoduje se s nativními podpisy požadavků CLI – **snižuje riziko zablokování a zároveň zachovává IP adresu proxy** |\n| 🌐 **Filtrování IP adres** | Ovládání seznamu povolených/blokovaných položek pro odhalená nasazení |\n| 📊 **Upravitelné limity rychlosti** | Konfigurovatelné globální/na úrovni poskytovatele limity s perzistencí |\n| 🔑 **Správa klíčů API a stanovení rozsahu** | Bezpečné vydávání/rotace klíčů a kontroly modelu/poskytovatele |\n| 🛡️ **Chráněné `/models`** | Volitelné ověřování a skrytí poskytovatele pro katalog modelů |\n\n### 📊 Pozorovatelnost a analytika\n\n| Funkce | Co to dělá |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| 📝 **Žádost + protokolování proxy** | Úplné protokolování požadavků/odpovědí a proxy |\n| 📋 **Sjednocený panel protokolů** | Zobrazení požadavků, proxy, auditu a konzole na jedné stránce |\n| 🔍 **Vyžádat si telemetrii** | Latence p50/p95/p99 a trasování požadavků |\n| 🏥 **Panel zdraví** | Doba provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti |\n| 💰 **Sledování nákladů** | Kontrola rozpočtu a přehled o cenách pro jednotlivé modely |\n| 📈 **Analytické vizualizace** | Přehledy využití modelů/poskytovatelů a zobrazení trendů |\n| 🧪 **Rámec hodnocení** | Testování zlaté sady s konfigurovatelnými strategiemi shody |\n\n### ☁️ Nasazení a platforma\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| 🌐 **Nasazení kdekoli** | Localhost, VPS, Docker, cloudová prostředí |\n| 💾 **Synchronizace s cloudem** | Synchronizace konfigurace přes cloud worker |\n| 🔄 **Zálohování/Obnovení** | Toky exportu/importu a obnovy po havárii |\n| 🧙 **Průvodce nástupem** | Průvodce prvním spuštěním |\n| 🔧 **Panel nástrojů CLI** | Nastavení oblíbených kódovacích nástrojů jedním kliknutím |\n| 🎮 **Modelové hřiště** | Otestujte libovolného poskytovatele/model/koncový bod z řídicího panelu |\n| 🔏 **Přepínač otisků prstů v příkazovém řádku** | Porovnávání otisků prstů podle poskytovatele v Nastavení &gt; Zabezpečení |\n| 🌐 **i18n (30 jazyků)** | Plná jazyková podpora dashboardu a dokumentace s psaním zprava doleva |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Adresář vlastních dat** | Přepsání `DATA_DIR` pro umístění úložiště |\n\n### Hluboký pohled na funkce\n\n#### Chytrá záložní funkce s praktickou kontrolou nákladů\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyž selže kvóta, rychlost nebo stav, OmniRoute automaticky přejde k dalšímu kandidátovi bez nutnosti ručního přepínání.\n\n#### Správa protokolů, která je viditelná a ovladatelná\n\n- MCP + A2A jsou viditelné v uživatelském rozhraní a dokumentaci (nejsou skryté)\n- API pro stav protokolu zpřístupňují živá provozní data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnují akce pro operace 2. dne (přepínání kombinací, resetování jističů, zrušení úkolů)\n\n#### Pracovní postup překladatele + validace\n\nOblast překladatele zahrnuje:\n\n- **Hřiště** : kontroly transformace požadavků\n- **Tester chatu** : kompletní okružní cesta požadavku/odpovědi\n- **Testovací stolice** : více případů v jednom běhu\n- **Živý monitor** : zobrazení provozu v reálném čase\n\nPlus validace protokolu se skutečnými klienty pomocí `npm run test:protocols:e2e` .\n\n> 📖 **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** — Referenční informace o nástrojích, konfigurace IDE a příklady klientů\n>\n> 📖 **[Soubor README pro A2A Server](src/lib/a2a/README.md)** — Dovednosti, metody JSON-RPC, streamování a životní cyklus úloh\n\n## 🧪 Hodnocení (Evals)\n\nOmniRoute obsahuje vestavěný hodnotící rámec pro testování kvality odpovědí LLM v porovnání se zlatou sadou. Přístup k němu je možný přes **Analýzy → Hodnocení** v dashboardu.\n\n### Vestavěná zlatá sada\n\nPředinstalovaná sada „OmniRoute Golden Set“ obsahuje testovací případy pro:\n\n- Zdravím, matematika, zeměpis, generování kódu\n- Shoda s formátem JSON, překlad, generování markdownů\n- Bezpečnostní odmítnutí (škodlivý obsah), počítání, booleovská logika\n\n### Strategie hodnocení\n\n| Strategie | Popis | Příklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Výstup se musí přesně shodovat | `\"4\"` |\n| `contains` | Výstup musí obsahovat podřetězec (bez rozlišení velkých a malých písmen) | `\"Paris\"` |\n| `regex` | Výstup musí odpovídat vzoru regulárních výrazů | `\"1.*2.*3\"` |\n| `custom` | Vlastní JS funkce vrací true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Průvodce nastavením\n\n### Nastavení protokolu (MCP + A2A)\n\n<details>\n<summary><b>🧩 Nastavení MCP (Model Context Protocol)</b></summary>\n</details>\n\nSpuštění MCP transportu v režimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporučený postup ověření:\n\n1. Připojte svého MCP klienta přes stdio.\n2. Spusťte `omniroute_get_health` .\n3. Spusťte `omniroute_list_combos` .\n4. Otevřete `/dashboard/mcp` pro ověření prezenčního signálu, aktivity a auditu.\n\nUžitečná API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n<details>\n<summary><b>🤝 Nastavení A2A (Agent2Agent)</b></summary>\n</details>\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat úkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSpráva životního cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvozní uživatelské rozhraní:\n\n- `/dashboard/a2a` pro pozorovatelnost úloh/stavů/streamů a akce kouření\n\n<details>\n<summary><b>🧪 Komplexní validace protokolu</b></summary>\n</details>\n\nOvěřte oba protokoly se skutečnými klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTím se ověřuje:\n\n- Připojení/seznam/volání klienta MCP SDK\n- A2A objevování/odesílání/streamování/získávání/zrušení\n- Křížová kontrola dat v auditu MCP a API pro správu úloh A2A\n\n<details>\n<summary><b>💳 Poskytovatelé předplatného</b></summary>\n</details>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionály:** Pro složité úkoly používejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvótu pro každý model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Správa limitů účtu Codex (5h + týdně)\n\nKaždý účet Codex má nyní přepínače zásad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinového prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zásadu týdenního prahu okna.\n- Prahové chování: když povolené okno dosáhne využití &gt;=90 %, je daný účet přeskočen.\n- Chování rotace: OmniRoute automaticky přesměruje na další způsobilý účet Codex.\n- Chování při resetování: Po `resetAt` určité doby se účet automaticky opět stane způsobilým.\n\nScénáře:\n\n- `5h ON` + `Weekly ON` : účet je přeskočen, když kterékoli z oken dosáhne prahové hodnoty.\n- `5h OFF` + `Weekly ON` : účet může být zablokován pouze týdenním používáním.\n- `5h ON` + `Weekly OFF` : účet může být zablokován pouze při 5hodinovém používání.\n- `resetAt` passed: účet se automaticky znovu zapne (bez ručního opětovného povolení).\n\n### Gemini CLI (ZDARMA 180 000/měsíc!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepší hodnota:** Obrovská bezplatná úroveň! Použijte ji před placenými úrovněmi.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n<details>\n<summary><b>🔑 Poskytovatelé klíčů API</b></summary>\n</details>\n\n### NVIDIA NIM (BEZPLATNÝ přístup pro vývojáře — více než 70 modelů)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Získejte zdarma klíč API (včetně 1000 inferenčních kreditů)\n3. Ovládací panel → Přidat poskytovatele → NVIDIA NIM:\n - Klíč API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a více než 50 dalších\n\n**Tip pro profesionály:** API kompatibilní s OpenAI – funguje bez problémů s překladem formátů OmniRoute!\n\n### Hluboké vyhledávání\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatná úroveň!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Získejte klíč API (včetně bezplatné úrovně)\n3. Ovládací panel → Přidat poskytovatele → Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionály:** Ultrarychlá inference – nejlepší pro kódování v reálném čase!\n\n### OpenRouter (100+ modelů)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → OpenRouter\n\n**Modely:** Získejte přístup k více než 100 modelům od všech hlavních poskytovatelů prostřednictvím jediného klíče API.\n\n<details>\n<summary><b>💰 Levní poskytovatelé (záložní)</b></summary>\n</details>\n\n### GLM-4.7 (Denní reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Získejte klíč API z kódovacího plánu\n3. Nástěnka → Přidat klíč API:\n - Poskytovatel: `glm`\n - Klíč API: `your-key`\n\n**Použití:** `glm/glm-4.7`\n\n**Tip pro profesionály:** Programovací plán nabízí 3× kvótu za cenu 1/7! Obnovuje se denně v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionály:** Nejlevnější varianta pro dlouhý kontext (1 milion tokenů)!\n\n### Kimi K2 (paušální poplatek 9 dolarů měsíčně)\n\n1. Odebírat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `kimi/kimi-latest`\n\n**Tip pro profesionály:** Fixních 9 $/měsíc za 10 milionů tokenů = efektivní náklady 0,90 $/1 milion!\n\n<details>\n<summary><b>🆓 BEZPLATNÍ poskytovatelé (nouzové zálohování)</b></summary>\n</details>\n\n### iFlow (5 BEZPLATNÝCH modelů přes OAuth)\n\n```bash\nDashboard → Connect iFlow\n→ iFlow OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kódem zařízení)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n<details>\n<summary><b>🎨 Vytvořte kombinace</b></summary>\n</details>\n\n### Příklad 1: Maximalizace předplatného → Levné zálohování\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Příklad 2: Pouze zdarma (nulové náklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n<details>\n<summary><b>🔧 Integrace s rozhraním příkazového řádku</b></summary>\n</details>\n\n### IDE kurzoru\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jedním kliknutím použijte stránku **Nástroje CLI** na řídicím panelu nebo ručně upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Možnost 1 – Dashboard (doporučeno):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Možnost 2 – Manuální úprava:** Úprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznámka:** OpenClaw funguje pouze s lokálním OmniRoute. Místo `localhost` použijte `127.0.0.1` , abyste se vyhnuli problémům s rozlišením IPv6.\n\n### Cline / Pokračovat / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Přidání OmniRoute jako vlastního poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvořte/upravte `opencode.json` v kořenovém adresáři projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` přidejte jakýkoli model dostupný ve vašem koncovém bodu OmniRoute `/v1/models` . Použijte formát `provider/model-id` z vašeho dashboardu OmniRoute.\n\n---\n\n## 🐛 Řešení problémů\n\n<details>\n<summary><b>Kliknutím rozbalíte průvodce řešením problémů</b></summary>\n</details>\n\n**\"Jazykový model neposkytoval zprávy\"**\n\n- Kvóta poskytovatele vyčerpána → Zkontrolujte sledování kvót na řídicím panelu\n- Řešení: Použijte záložní kombinovanou variantu nebo přejděte na levnější úroveň\n\n**Omezení rychlosti**\n\n- Kvóta předplatného vyčerpána → Přechod na GLM/MiniMax\n- Přidat kombo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vypršela**\n\n- Automaticky aktualizováno službou OmniRoute\n- Pokud problémy přetrvávají: Ovládací panel → Poskytovatel → Znovu připojit\n\n**Vysoké náklady**\n\n- Zkontrolujte statistiky využití v sekci Nástěnka → Náklady\n- Přepnout primární model na GLM/MiniMax\n- Pro nekritické úlohy použijte bezplatnou úroveň (Gemini CLI, iFlow).\n\n**Porty řídicího panelu/API jsou nesprávné**\n\n- `PORT` je kanonický základní port (a standardně port API)\n- `API_PORT` přepisuje pouze posluchač API kompatibilní s OpenAI.\n- `DASHBOARD_PORT` přepisuje pouze posluchač dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaši veřejnou URL adresu řídicího panelu (pro zpětná volání OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ověřte, zda `BASE_URL` odkazuje na vaši spuštěnou instanci.\n- Ověřte, zda `CLOUD_URL` odkazuje na váš očekávaný cloudový koncový bod.\n- Udržujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na straně serveru.\n\n**První přihlášení nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud není nastaveno, záložní heslo je `123456`\n\n**Žádné protokoly požadavků**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test připojení ukazuje „Neplatné“ pro poskytovatele kompatibilní s OpenAI**\n\n- Mnoho poskytovatelů nezpřístupňuje koncový bod `/models`\n- OmniRoute v1.0.6+ zahrnuje záložní ověření pomocí dokončení chatu\n- Zajistěte, aby základní URL adresa obsahovala příponu `/v1`\n\n### 🔐 OAuth na vzdáleném serveru\n\n<a name=\"oauth-on-a-remote-server\"></a>\n\n> **⚠️ Důležité pro uživatele, kteří provozují OmniRoute na VPS, Dockeru nebo jakémkoli vzdáleném serveru**\n\n#### Proč selhává OAuth v rozhraní CLI Antigravity / Gemini na vzdálených serverech?\n\nPoskytovatelé rozhraní CLI **Antigravity** a **Gemini** používají **Google OAuth 2.0** . Google vyžaduje, aby se `redirect_uri` v toku OAuth přesně shodoval s jedním z předregistrovaných URI v konzoli Google Cloud Console aplikace.\n\nPřihlašovací údaje OAuth, které jsou součástí OmniRoute, jsou registrovány **pouze pro `localhost`** . Když přistupujete k OmniRoute na vzdáleném serveru (např. `https://omniroute.myserver.com` ), Google odmítne ověření pomocí:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Řešení: Nakonfigurujte si vlastní přihlašovací údaje OAuth\n\nV Google Cloud Console je potřeba vytvořit **ID klienta OAuth 2.0** s URI vašeho serveru.\n\n#### Krok za krokem\n\n**1. Otevřete konzoli Google Cloud**\n\nPřejděte na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvořte nové ID klienta OAuth 2.0**\n\n- Klikněte na **„+ Vytvořit přihlašovací údaje“** → **„ID klienta OAuth“**\n- Typ aplikace: **„Webová aplikace“**\n- Název: cokoli chcete (např. `OmniRoute Remote` )\n\n**3. Přidejte autorizované URI pro přesměrování**\n\nDo pole **„Autorizované identifikátory URI pro přesměrování“** přidejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraďte `your-server.com` doménou nebo IP adresou vašeho serveru (v případě potřeby uveďte i port, např. `http://45.33.32.156:20128/callback` ).\n\n**4. Uložte a zkopírujte přihlašovací údaje**\n\nPo vytvoření Google zobrazí **ID klienta** a **tajný kód klienta** .\n\n**5. Nastavení proměnných prostředí**\n\nVe vašem souboru `.env` (nebo proměnných prostředí Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu připojit**\n\nŘídicí panel → Poskytovatelé → Antigravity (nebo Gemini CLI) → OAuth\n\nGoogle nyní bude správně přesměrovávat na `https://your-server.com/callback` .\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nPokud si teď nechcete nastavovat vlastní přihlašovací údaje, můžete stále použít **ruční postup pro URL** :\n\n1. OmniRoute otevírá autorizační URL od Googlu\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru).\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče (i když se stránka nenačte)\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute.\n5. Klikněte na **„Připojit“**\n\n> To funguje, protože autorizační kód v URL adrese je platný bez ohledu na to, zda se načetla přesměrovací stránka.\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nChcete-li získat přístup k přihlašovacím údajům bez vlastní konfigurace, můžete použít následující postup:\n\n1. OmniRoute otevře URL autorizace Google\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru)\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute\n5. Klikněte na **„Připojit\"**\n\n> Toto řešení funguje, protože autorizační kód v URL adrese je platný bez ohledu na načtení přesměrovací stránky.\n\n---\n\n## 🛠️ Technologický stack\n\n<details>\n<summary><b>Kliknutím rozbalíte podrobnosti o technologickém stacku</b></summary>\n</details>\n\n- **Runtime** : Node.js 18–22 LTS (⚠️ Node.js 24+ **není podporován** — nativní binární soubory `better-sqlite3` jsou nekompatibilní)\n- **Jazyk** : TypeScript 5.9 — **100% TypeScript** napříč `src/` a `open-sse/` ( `any` v základních modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databáze** : LowDB (JSON) + SQLite (stav domény + protokoly proxy + audit MCP + rozhodnutí o směrování)\n- **Schémata** : Zod (validace I/O nástrojů MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamování** : Události odeslané serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klíče + autorizace s rozsahem MCP\n- **Testování** : Node.js test runner + Vitest (900+ testů včetně unit, integračních, E2E)\n- **CI/CD** : Akce GitHubu (automatické publikování v npm + Docker Hub při vydání)\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **Balíček** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistič, exponenciální odstavení, ochrana proti hromům, falešné TLS, automatické kombinované samoopravování\n\n---\n\n## 📖 Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uživatelská příručka](docs/USER_GUIDE.md) | Poskytovatelé, kombinace, integrace CLI, nasazení |\n| [Referenční informace k API](docs/API_REFERENCE.md) | Všechny koncové body s příklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nástrojů MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamování, správa úloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorové bodování, balíčky režimů, samoléčba |\n| [Odstraňování problémů](docs/TROUBLESHOOTING.md) | Běžné problémy a jejich řešení |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a interní prvky systému |\n| [Přispívání](CONTRIBUTING.md) | Nastavení a pokyny pro vývoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpečnostní zásady](SECURITY.md) | Hlášení zranitelností a bezpečnostní postupy |\n| [Nasazení virtuálního počítače](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletní průvodce: Nastavení virtuálního počítače + nginx + Cloudflare |\n| [Galerie funkcí](docs/FEATURES.md) | Vizuální prohlídka řídicího panelu se snímky obrazovky |\n| [Kontrolní seznam vydání](docs/RELEASE_CHECKLIST.md) | Kroky ověření před vydáním |\n\n---\n\n## 🗺️ Plán\n\nOmniRoute má **v plánu více než 210 funkcí** v několika fázích vývoje. Zde jsou klíčové oblasti:\n\n| Kategorie | Plánované funkce | Hlavní body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| 🧠 **Směrování a inteligence** | 25+ | Směrování s nejnižší latencí, směrování založené na tagech, kontrola kvót před výstupem, výběr účtu P2C |\n| 🔒 **Zabezpečení a dodržování předpisů** | 20+ | Zpevnění SSRF, maskování přihlašovacích údajů, limit rychlosti pro každý koncový bod, stanovení rozsahu klíčů pro správu |\n| 📊 **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledování kvót v reálném čase, sledování nákladů podle modelu |\n| 🔄 **Integrace poskytovatelů** | 20+ | Dynamický registr modelů, doba zchlazení poskytovatelů, Codex pro více účtů, analýza kvót Copilota |\n| ⚡ **Výkon** | 15+ | Dvojitá vrstva mezipaměti, mezipaměť výzev, mezipaměť odpovědí, udržování streamování, dávkové API |\n| 🌐 **Ekosystém** | 10+ | WebSocket API, horké opětovné načítání konfigurace, distribuované úložiště konfigurace, komerční režim |\n\n### 🔜 Již brzy\n\n- 🔗 **Integrace OpenCode** — Nativní podpora poskytovatelů pro IDE kódování s AI v OpenCode\n- 🔗 **Integrace TRAE** — Plná podpora vývojového rámce TRAE pro umělou inteligenci\n- 📦 **Dávkové API** — Asynchronní dávkové zpracování hromadných požadavků\n- 🎯 **Směrování na základě tagů** — Směrování požadavků na základě vlastních tagů a metadat\n- 💰 **Strategie nejnižších nákladů** – Automaticky vybere nejlevnějšího dostupného poskytovatele\n\n> 📝 Úplné specifikace funkcí jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobných specifikací)\n\n---\n\n## 👥 Přispěvatelé\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Přispěvatelé](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak přispět\n\n1. Vytvoření forku repozitáře\n2. Vytvořte si vlastní větev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrďte změny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do větve ( `git push origin feature/amazing-feature` )\n5. Otevřít žádost o změny (pull request)\n\nPodrobné pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydání nové verze\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Hvězdná historie\n\n## Hvězdáři v průběhu času\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvězdáři v průběhu času](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## 🙏 Poděkování\n\nZvláštní poděkování patří **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** – původnímu projektu, který inspiroval tento fork. OmniRoute staví na tomto neuvěřitelném základu s dalšími funkcemi, multimodálními API a kompletním přepsáním TypeScriptu.\n\nZvláštní poděkování patří **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – původní implementaci Go, která inspirovala tento JavaScriptový port.\n\n---\n\n## 📄 Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n<div align=\"center\">\n <sub>Vytvořeno s ❤️ pro vývojáře, kteří programují 24 hodin denně, 7 dní v týdnu</sub>\n <br>\n <sub><p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\">omniroute.online</a></p></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "8182825e92dd0b46ae7d855196abb897f9bc23e5": {"t": 1785764464.5762768, "n": 92325, "h": "844c1ed70cd6a6fc", "c": "# 🚀 OmniRoute — Bezplatná brána umělé inteligence\n\n### Nikdy nepřestávejte s kódováním. Chytré směrování k **BEZPLATNÝM a levným modelům AI** s automatickým přepínáním mezi záložními systémy.\n\n_Váš univerzální API proxy – jeden endpoint, více než 44 poskytovatelů, nulové výpadky. Nyní s orchestrací agentů **MCP a A2A** ._\n\n**Dokončení chatu • Vkládání • Generování obrázků • Video • Hudba • Audio • Změna pořadí • **Vyhledávání na webu** • MCP server • A2A protokol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n</div>\n<p data-md-type=\"paragraph\"><a href=\"https://www.npmjs.com/package/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/npm/v/omniroute?color=cb3837&amp;logo=npm\" alt=\"verze npm\" data-md-type=\"image\"><a href=\"https://hub.docker.com/r/diegosouzapw/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&amp;logo=docker&amp;color=2496ED\" alt=\"Docker Hub\" data-md-type=\"image\"><a href=\"https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/github/license/diegosouzapw/OmniRoute\" alt=\"Licence\" data-md-type=\"image\"><a href=\"https://omniroute.online\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&amp;logoColor=white\" alt=\"Webové stránky\" data-md-type=\"image\"><a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&amp;logoColor=white\" alt=\"WhatsApp\" data-md-type=\"image\"></p>\n<p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\" data-md-type=\"link\">🌐 Webové stránky</a> • <a href=\"#-quick-start\" data-md-type=\"link\">🚀 Rychlý start</a> • <a href=\"#-key-features\" data-md-type=\"link\">💡 Funkce</a> • <a href=\"#-documentation\" data-md-type=\"link\">📖 Dokumentace</a> • <a href=\"#-pricing-at-a-glance\" data-md-type=\"link\">💰 Ceník</a> • <a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\">💬 WhatsApp</a></p>\n<div data-md-type=\"block_html\"></div>\n\n🌐 **Dostupné v:** 🇺🇸 [Angličtina](README.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [maďarština](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonésie](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nizozemsko](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)\n\n---\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n## 🖼️ Hlavní ovládací panel\n\n<div align=\"center\"> <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"Řídicí panel OmniRoute\" width=\"800\"> </div>\n\n---\n\n## 📸 Náhled řídicího panelu\n\n<details>\n<summary><b>Kliknutím zobrazíte snímky obrazovky z řídicího panelu</b></summary>\n</details>\n\n| Strana | Snímek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelé** | ![Poskytovatelé](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdraví** | ![Zdraví](docs/screenshots/04-health.png) |\n| **Překladatel** | ![Překladatel](docs/screenshots/05-translator.png) |\n| **Nastavení** | ![Nastavení](docs/screenshots/06-settings.png) |\n| **Nástroje CLI** | ![Nástroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly používání** | ![Používání](docs/screenshots/08-usage.png) |\n| **Koncové body** | ![Koncové body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### 🤖 Bezplatný poskytovatel umělé inteligence pro vaše oblíbené programátory\n\n_Připojte libovolný nástroj IDE nebo CLI s umělou inteligencí přes OmniRoute — bezplatnou API bránu pro neomezené kódování._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openclaw/openclaw\"><img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"><br><b>OpenClaw</b></a><br> <sub>⭐ 205 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/HKUDS/nanobot\"><img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"><br><b>NanoBot</b></a><br> <sub>⭐ 20,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/sipeed/picoclaw\"><img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"><br><b>PicoClaw</b></a><br> <sub>⭐ 14,6 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/zeroclaw-labs/zeroclaw\"><img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"><br><b>ZeroClaw</b></a><br> <sub>⭐ 9,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/nearai/ironclaw\"><img src=\"./public/providers/ironclaw.png\" alt=\"Železný dráp\" width=\"48\"><br><b>Železný dráp</b></a><br> <sub>⭐ 2,1 tisíce</sub> </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anomalyco/opencode\"><img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"><br><b>OpenCode</b></a><br> <sub>⭐ 106 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openai/codex\"><img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"><br><b>Codex CLI</b></a><br> <sub>⭐ 60,8 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anthropics/claude-code\"><img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"><br><b>Claude Code</b></a><br> <sub>⭐ 67,3 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/google-gemini/gemini-cli\"><img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"><br> <b>Gemini CLI</b></a><br> <sub>⭐ 94,7 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/Kilo-Org/kilocode\"><img src=\"./public/providers/kilocode.png\" alt=\"Kilo kód\" width=\"48\"><br><b>Kilo kód</b></a><br> <sub>⭐ 15,5 tisíc</sub> </td>\n </tr>\n </table>\n\n<sub>📡 Všichni agenti se připojují přes <code>http://localhost:20128/v1</code> nebo <code>http://cloud.omniroute.online/v1</code> — jedna konfigurace, neomezené modely a kvóty</sub>\n\n---\n\n## 🤔 Proč OmniRoute?\n\n**Přestaňte plýtvat penězi a narážet na limity:**\n\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Kvóta předplatného vyprší každý měsíc\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Limity rychlosti vám zabrání v kódování\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Drahá API (20–50 USD/měsíc na poskytovatele)\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Ruční přepínání mezi poskytovateli\n\n**OmniRoute to řeší:**\n\n- ✅ **Maximalizujte předplatné** – Sledujte kvótu, využijte každou částku před resetováním\n- ✅ **Automatické záložní** – Předplatné → API klíč → Levné → Zdarma, žádné výpadky\n- ✅ **Více účtů** – Round-robin mezi účty u jednotlivých poskytovatelů\n- ✅ **Univerzální** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakýmkoli nástrojem CLI\n\n---\n\n## 📧 Podpora\n\n> 💬 **Přidejte se k naší komunitě!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získejte pomoc, sdílejte tipy a buďte v obraze.\n\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problémy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitní skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Přispívání** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevřete žádost o příspěvek nebo si vyberte `good first issue`\n- **Původní projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### 🐛 Hlásíte chybu?\n\nPři otevírání problému spusťte příkaz system-info a přiložte vygenerovaný soubor:\n\n```bash\nnpm run system-info\n```\n\nTím se vygeneruje soubor `system-info.txt` s verzí Node.js, verzí OmniRoute, podrobnostmi o operačním systému, nainstalovanými nástroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systémovými balíčky – vše, co potřebujeme k rychlé reprodukci vašeho problému. Soubor přiložte přímo k vašemu problému na GitHubu.\n\n---\n\n## 🔄 Jak to funguje\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 Co řeší OmniRoute — 30 skutečných problémů a případů použití\n\n> **Každý vývojář používající nástroje umělé inteligence se s těmito problémy setkává denně.** OmniRoute byl vytvořen tak, aby je všechny vyřešil – od překročení nákladů po regionální bloky, od nefunkčních toků OAuth až po operace s protokoly a sledovatelnost v podniku.\n\n<details>\n<summary><b>💸 1. „Platím si drahé předplatné, ale stále mě ruší limity“</b></summary>\n</details>\n\nVývojáři platí za Claude Pro, Codex Pro nebo GitHub Copilot 20–200 dolarů měsíčně. I při platbě má kvóta strop – 5 hodin používání, týdenní limity nebo limity rychlosti za minutu. Uprostřed kódovací relace poskytovatel přestane reagovat a vývojář ztrácí plynulost a produktivitu.\n\n**Jak to OmniRoute řeší:**\n\n- **Inteligentní čtyřúrovňová záložní služba** – Pokud dojde kvóta předplatného, ​​automaticky se přesměruje na API klíč → Levné → Zdarma bez manuálního zásahu\n- **Sledování kvót v reálném čase** – Zobrazuje spotřebu tokenů v reálném čase s odpočítáváním resetování (5 hodin, denně, týdně)\n- **Podpora více účtů** – Více účtů u jednoho poskytovatele s automatickým přepínáním – když jeden dojde, přepne se na další\n- **Vlastní kombinace** — Přizpůsobitelné záložní řetězce se 6 strategiemi vyvažování (fill-first, round robin, P2C, náhodné, nejméně používané, nákladově optimalizované)\n- **Codex Business Quotas** — Sledování kvót pracovního prostoru firmy/týmu přímo v dashboardu\n\n<details>\n<summary><b>🔌 2. „Potřebuji použít více poskytovatelů, ale každý má jiné API“</b></summary>\n</details>\n\nOpenAI používá jeden formát, Claude (Anthropic) jiný a Gemini ještě třetí. Pokud chce vývojář testovat modely od různých poskytovatelů nebo mezi nimi přecházet, musí překonfigurovat SDK, změnit koncové body a vypořádat se s nekompatibilními formáty. Vlastní poskytovatelé (FriendLI, NIM) mají nestandardní koncové body modelů.\n\n**Jak to OmniRoute řeší:**\n\n- **Sjednocený koncový bod** — Jeden `http://localhost:20128/v1` slouží jako proxy pro všech 67+ poskytovatelů.\n- **Překlad formátu** — Automatický a transparentní: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Sanitizace odpovědí** — Odstraňuje nestandardní pole ( `x_groq` , `usage_breakdown` , `service_tier` ), která porušují OpenAI SDK v1.83+\n- **Normalizace rolí** — Převádí `developer` → `system` pro poskytovatele bez OpenAI; `system` → `user` pro GLM/ERNIE\n- **Extrakce tagů Think** — Extrahuje bloky `<think>` z modelů, jako je DeepSeek R1, do standardizovaného `reasoning_content`\n- **Strukturovaný výstup pro Gemini** — `json_schema` → automatická konverze `responseMimeType` / `responseSchema`\n- **Výchozí hodnota `stream` je `false`** – Odpovídá specifikaci OpenAI, čímž se zabrání neočekávanému SSE v Python/Rust/Go SDK.\n\n<details>\n<summary><b>🌐 3. „Můj poskytovatel AI blokuje můj region/zemi“</b></summary>\n</details>\n\nPoskytovatelé jako OpenAI/Codex blokují přístup z určitých geografických oblastí. Uživatelé se během připojení OAuth a API dostávají k chybám jako `unsupported_country_region_territory` . To je obzvláště frustrující pro vývojáře z rozvojových zemí.\n\n**Jak to OmniRoute řeší:**\n\n- **3úrovňová konfigurace proxy** – Konfigurovatelná proxy na 3 úrovních: globální (veškerý provoz), pro jednotlivé poskytovatele (pouze jeden poskytovatel) a pro jednotlivé připojení/klíč\n- **Barevně kódované odznaky proxy** – Vizuální indikátory: 🟢 globální proxy, 🟡 proxy poskytovatele, 🔵 proxy připojení, vždy zobrazující IP adresu\n- **Výměna tokenů OAuth prostřednictvím proxy** – tok OAuth také prochází přes proxy, čímž se řeší `unsupported_country_region_territory`\n- **Testy připojení přes proxy** – Testy připojení používají nakonfigurovaný proxy (již žádné přímé obcházení)\n- **Podpora SOCKS5** — Plná podpora proxy SOCKS5 pro odchozí směrování\n- **TLS Fingerprint Spoofing** — Otisk prstu TLS podobný prohlížeči pomocí `wreq-js` pro obcházení detekce botů\n- **🔏 Porovnávání otisků prstů v CLI** — Změní pořadí záhlaví a polí v těle serveru tak, aby odpovídala nativním binárním podpisům v CLI, čímž drasticky snižuje riziko nahlašování účtu. IP adresa proxy je zachována — získáte současně stealth **i** maskování IP adresy.\n\n<details>\n<summary><b>🆓 4. „Chci používat umělou inteligenci pro kódování, ale nemám peníze“</b></summary>\n</details>\n\nNe každý si může dovolit zaplatit 20–200 dolarů měsíčně za předplatné AI. Studenti, vývojáři z rozvíjejících se zemí, amatéři a freelanceři potřebují přístup ke kvalitním modelům za nulovou cenu.\n\n**Jak to OmniRoute řeší:**\n\n- **Vestavění poskytovatelé bezplatné úrovně** — Nativní podpora pro 100% bezplatné poskytovatele: iFlow (5 neomezených modelů přes OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezené modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisíc tokenů/měsíc zdarma)\n- **Ollama Cloud** — Cloudově hostované modely Ollama na `api.ollama.com` s bezplatnou úrovní „Light usage“; použijte prefix `ollamacloud/<model>`\n- **Kombinace pouze zdarma** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/měsíc s nulovými prostoji\n- **NVIDIA NIM Free Access** — ~40 RPM developerský přístup k více než 70 modelům na build.nvidia.com (přechod z kreditů na čisté limity rychlosti)\n- **Strategie optimalizace nákladů** – Strategie směrování, která automaticky vybere nejlevnějšího dostupného poskytovatele\n\n<details>\n<summary><b>🔒 5. „Potřebuji chránit svou bránu umělé inteligence před neoprávněným přístupem“</b></summary>\n</details>\n\nPři zpřístupnění brány umělé inteligence síti (LAN, VPS, Docker) může kdokoli s adresou spotřebovat tokeny/kvótu vývojáře. Bez ochrany jsou API zranitelná vůči zneužití, prompt injection a dalšímu zneužití.\n\n**Jak to OmniRoute řeší:**\n\n- **Správa klíčů API** – generování, rotace a vymezování rozsahu pro každého poskytovatele s vyhrazenou stránkou `/dashboard/api-manager`\n- **Oprávnění na úrovni modelu** – Omezení klíčů API na konkrétní modely ( `openai/*` , zástupné znaky) pomocí přepínače Povolit vše/Omezit\n- **Ochrana koncových bodů API** – Vyžaduje klíč pro `/v1/models` a blokuje konkrétní poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** — Všechny trasy dashboardu chráněné middlewarem `withAuth` + tokeny CSRF\n- **Omezovač rychlosti** — Omezování rychlosti na IP s konfigurovatelnými okny\n- **Filtrování IP adres** — Seznam povolených/blokovaných adres pro řízení přístupu\n- **Ochrana proti vkládání výzev** – Sanitizace proti škodlivým vzorcům výzev\n- **Šifrování AES-256-GCM** – přihlašovací údaje jsou v klidovém stavu šifrovány\n\n<details>\n<summary><b>🛑 6. „Můj poskytovatel selhal a já ztratil/a programovací tok“</b></summary>\n</details>\n\nPoskytovatelé umělé inteligence se mohou stát nestabilními, vracet chyby 5xx nebo dosáhnout dočasných limitů rychlosti. Pokud je vývojář závislý na jediném poskytovateli, je jeho práce přerušena. Bez jističů může opakované pokusy vést k pádu aplikace.\n\n**Jak to OmniRoute řeší:**\n\n- **Jistič pro každý model** – Automatické otevírání/zavírání s konfigurovatelnými prahovými hodnotami a dobou ochlazování (Zavřeno/Otevřeno/Poloviční otevření), rozsah definovaný pro každý model, aby se zabránilo kaskádování bloků\n- **Exponenciální odklad** — Progresivní zpoždění opakování\n- **Anti-Thundering Herd** — ochrana Mutex + semafor proti souběžným bouřím s opakovanými pokusy\n- **Kombinované záložní řetězce** – Pokud primární poskytovatel selže, automaticky se propadne řetězcem bez zásahu.\n- **Kombinovaný jistič** – Automaticky deaktivuje selhávajícího poskytovatele v rámci kombinovaného řetězce\n- **Dashboard stavu** — Monitorování provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti, latence p50/p95/p99\n\n<details>\n<summary><b>🔧 7. „Konfigurace každého nástroje umělé inteligence je zdlouhavá a opakující se“</b></summary>\n</details>\n\nVývojáři používají Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Každý nástroj potřebuje jinou konfiguraci (API endpoint, klíč, model). Překonfigurování při změně poskytovatele nebo modelu je ztráta času.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel nástrojů CLI** — Vyhrazená stránka s nastavením jedním kliknutím pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generátor konfigurace GitHub Copilot** – Generuje `chatLanguageModels.json` pro VS Code s hromadným výběrem modelu\n- **Průvodce zaváděním** – 4krokové nastavení pro začínající uživatele\n- **Jeden koncový bod, všechny modely** – jednou nakonfigurujte `http://localhost:20128/v1` a získejte přístup k více než 44 poskytovatelům\n\n<details>\n<summary><b>🔑 8. „Správa OAuth tokenů od více poskytovatelů je peklo“</b></summary>\n</details>\n\nClaude Code, Codex, Gemini CLI, Copilot – všechny používají OAuth 2.0 s tokeny s vypršením platnosti. Vývojáři se musí neustále znovu autentizovat, řešit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdálených serverech. Obzvláště problematický je OAuth v LAN/VPS.\n\n**Jak to OmniRoute řeší:**\n\n- **Automatická aktualizace tokenů** – Tokeny OAuth se obnovují na pozadí před vypršením platnosti.\n- **Vestavěný OAuth 2.0 (PKCE)** – Automatický tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** — Více účtů na poskytovatele prostřednictvím extrakce tokenů JWT/ID\n- **OAuth LAN/Remote Fix** — Detekce privátní IP adresy pro `redirect_uri` + manuální režim URL pro vzdálené servery\n- **OAuth Behind Nginx** — Používá `window.location.origin` pro kompatibilitu s reverzní proxy\n- **Průvodce vzdáleným OAuth** – Podrobný návod k přihlašovacím údajům Google Cloud na VPS/Dockeru\n\n<details>\n<summary><b>📊 9. „Nevím, kolik utrácím ani kde“</b></summary>\n</details>\n\nVývojáři používají více placených poskytovatelů, ale nemají jednotný přehled o výdajích. Každý poskytovatel má svůj vlastní fakturační panel, ale neexistuje žádný konsolidovaný přehled. Mohou se hromadit neočekávané náklady.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard pro analýzu nákladů** – Sledování nákladů na token a správa rozpočtu pro každého poskytovatele\n- **Rozpočtové limity na úroveň** – Strop výdajů na úroveň, který spouští automatický záložní režim\n- **Konfigurace cen podle modelu** – Konfigurovatelné ceny podle modelu\n- **Statistiky použití pro každý klíč API** — Počet požadavků a časové razítko posledního použití pro každý klíč\n- **Analytický panel** – Statistické karty, graf využití modelu, tabulka poskytovatelů s mírou úspěšnosti a latencí\n\n<details>\n<summary><b>🐛 10. „Nedokážu diagnostikovat chyby a problémy ve volání umělé inteligence.“</b></summary>\n</details>\n\nKdyž volání selže, vývojář neví, zda se jednalo o limit rychlosti, vypršelý token, špatný formát nebo chybu poskytovatele. Fragmentované protokoly napříč různými terminály. Bez sledovatelnosti je ladění metodou pokus-omyl.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel jednotných protokolů** – 4 karty: Protokoly požadavků, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlížeč protokolů konzole** — Prohlížeč protokolů v reálném čase ve stylu terminálu s barevně kódovanými úrovněmi, automatickým posouváním, vyhledáváním a filtrováním\n- **Protokoly proxy SQLite** – trvalé protokoly, které přežijí restart serveru\n- **Překladačské hřiště** — 4 režimy ladění: Hřiště (překlad formátu), Tester chatu (okružní), Testovací stůl (dávkový), Živý monitor (v reálném čase)\n- **Telemetrie požadavků** — latence p50/p95/p99 + trasování X-Request-Id\n- **Souborové protokolování s rotací** – Konzolový interceptor zachycuje vše do protokolu JSON s rotací na základě velikosti\n- **Zpráva o systémových informacích** — příkaz `npm run system-info` vygeneruje `system-info.txt` s kompletním popisem vašeho prostředí (verze uzlu, verze OmniRoute, operační systém, nástroje CLI, stav Dockeru/PM2). Přiložte jej při hlášení problémů pro okamžité třídění.\n\n<details>\n<summary><b>🏗️ 11. „Nasazení a údržba brány je složitá“</b></summary>\n</details>\n\nInstalace, konfigurace a údržba AI proxy v různých prostředích (lokální, VPS, Docker, cloud) je pracná. Problémy, jako jsou pevně zakódované cesty, `EACCES` u adresářů, konflikty portů a multiplatformní sestavení, přispívají k obtížím.\n\n**Jak to OmniRoute řeší:**\n\n- **npm globální instalace** — `npm install -g omniroute && omniroute` — hotovo\n- **Docker Multi-Platform** — AMD64 + nativní ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** — `base` (bez nástrojů CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopová aplikace Electron** — Nativní aplikace pro Windows/macOS/Linux se systémovou lištou, automatickým spuštěním a offline režimem\n- **Režim rozdělených portů** – API a řídicí panel na samostatných portech pro pokročilé scénáře (reverzní proxy, síťování kontejnerů)\n- **Cloud Sync** – Konfigurace synchronizace mezi zařízeními pomocí Cloudflare Workers\n- **Zálohy databází** — Automatické zálohování, obnovení, export a import všech nastavení\n\n<details>\n<summary><b>🌍 12. „Rozhraní je pouze v angličtině a můj tým nemluví anglicky“</b></summary>\n</details>\n\nTýmy v neanglicky mluvících zemích, zejména v Latinské Americe, Asii a Evropě, se potýkají s rozhraními pouze v angličtině. Jazykové bariéry snižují míru přijetí a zvyšují chyby v konfiguraci.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard i18n — 30 jazyků** — Všech 500+ kláves je přeloženo včetně arabštiny, bulharštiny, dánštiny, němčiny, španělštiny, finštiny, francouzštiny, hebrejštiny, hindštiny, maďarštiny, indonéštiny, italštiny, japonštiny, korejštiny, malajštiny, holandštiny, norštiny, polštiny, portugalštiny (PT/BR), rumunštiny, ruštiny, slovenštiny, švédštiny, thajštiny, ukrajinštiny, vietnamštiny, čínštiny, filipínštiny a angličtiny\n- **Podpora RTL** – Podpora psaní zprava doleva pro arabštinu a hebrejštinu\n- **Vícejazyčné soubory README** — 30 kompletních překladů dokumentace\n- **Výběr jazyka** — Ikona glóbu v záhlaví pro přepínání v reálném čase\n\n<details>\n<summary><b>🔄 13. „Potřebuji víc než jen chat – potřebuji vložené soubory, obrázky, zvuk.“</b></summary>\n</details>\n\nUmělá inteligence není jen dokončování chatu. Vývojáři potřebují generovat obrázky, přepisovat zvuk, vytvářet embeddedy pro RAG, měnit pořadí dokumentů a moderovat obsah. Každé API má jiný koncový bod a formát.\n\n**Jak to OmniRoute řeší:**\n\n- **Vkládání** — `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generování obrázků** — `/v1/images/generations` s 10 poskytovateli a více než 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Převod textu na video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Převod textu na hudbu** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Přepis zvuku** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Převod textu na řeč** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a další stávající poskytovatelé\n- **Moderování** — `/v1/moderations` — Kontroly bezpečnosti obsahu\n- **Změna pořadí** — `/v1/rerank` — Změna pořadí relevance dokumentu\n- **Responses API** — Plná podpora `/v1/responses` pro Codex\n\n<details>\n<summary><b>🧪 14. „Nemám způsob, jak testovat a porovnávat kvalitu napříč modely.“</b></summary>\n</details>\n\nVývojáři chtějí vědět, který model je pro jejich případ použití nejlepší – kód, překlad, uvažování – ale ruční porovnávání je pomalé. Neexistují žádné integrované nástroje pro vyhodnocování.\n\n**Jak to OmniRoute řeší:**\n\n- **Hodnocení LLM** — Testování Golden setu s 10 předinstalovanými případy zahrnujícími pozdravy, matematiku, geografii, generování kódu, dodržování JSON, překlad, markdown, odmítnutí bezpečnostních požadavků\n- **4 strategie shody** — `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovací lavice pro překladatelské hřiště** — Dávkové testování s více vstupy a očekávanými výstupy, porovnání napříč poskytovateli\n- **Tester chatu** — Kompletní okružní cesta s vizuálním vykreslováním odpovědí\n- **Živý monitor** — Stream všech požadavků procházejících proxy serverem v reálném čase\n\n<details>\n<summary><b>📈 15. „Potřebuji škálovat bez ztráty výkonu“</b></summary>\n</details>\n\nS rostoucím objemem požadavků generují stejné otázky bez ukládání do mezipaměti duplicitní náklady. Bez idempotence duplicitní požadavky plýtvají zpracováním. Je nutné dodržovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute řeší:**\n\n- **Sémantická mezipaměť** — Dvouvrstvá mezipaměť (signatura + sémantika) snižuje náklady a latenci\n- **Idempotence požadavku** — 5s deduplikační okno pro identické požadavky\n- **Detekce limitu rychlosti** – sledování otáček za minutu (RPM), minimální mezera a maximální souběžné sledování pro každého poskytovatele\n- **Upravitelné limity rychlosti** — Konfigurovatelné výchozí hodnoty v Nastavení → Odolnost s perzistencí\n- **Mezipaměť pro ověření klíčů API** — třívrstvá mezipaměť pro výkon produkčního prostředí\n- **Dashboard s telemetrií** – latence p50/p95/p99, statistiky mezipaměti, dostupnost\n\n<details>\n<summary><b>🤖 16. „Chci mít chování modelů globálně pod kontrolou“</b></summary>\n</details>\n\nVývojáři, kteří chtějí všechny odpovědi v určitém jazyce, se specifickým tónem nebo chtějí omezit tokeny pro uvažování. Konfigurace této funkce v každém nástroji/požadavku je nepraktická.\n\n**Jak to OmniRoute řeší:**\n\n- **Vložení systémového prompt** – Globální prompt aplikovaný na všechny požadavky\n- **Validace rozpočtu Thinking** — Řízení alokace tokenů na požadavek (průchozí, automatické, vlastní, adaptivní)\n- **6 strategií směrování** – Globální strategie, které určují, jak jsou požadavky distribuovány\n- **Směrovač se zástupnými znaky** — vzory `provider/*` dynamicky směrují k libovolnému poskytovateli\n- **Přepínání povolení/zakázání kombinací** – Přepínání kombinací přímo z řídicího panelu\n- **Přepínání poskytovatele** – Povolení/zakázání všech připojení pro poskytovatele jedním kliknutím\n- **Blokovaní poskytovatelé** – Vyloučení konkrétních poskytovatelů ze seznamu `/v1/models`\n\n<details>\n<summary><b>🧰 17. „Potřebuji nástroje MCP jako prvotřídní produktové funkce.“</b></summary>\n</details>\n\nMnoho bran umělé inteligence odhaluje MCP pouze jako skrytý implementační detail. Týmy potřebují viditelnou a spravovatelnou operační vrstvu.\n\n**Jak to OmniRoute řeší:**\n\n- MCP se zobrazuje v navigaci na řídicím panelu a na kartě protokolu koncového bodu.\n- Vyhrazená stránka pro správu MCP s procesy, nástroji, rozsahy a auditem\n- Vestavěný rychlý start pro `omniroute --mcp` a onboarding klienta\n\n<details>\n<summary><b>🧠 18. „Potřebuji orchestraci A2A se synchronizací a cestami úloh streamu.“</b></summary>\n</details>\n\nPracovní postupy agentů vyžadují jak přímé odpovědi, tak dlouhodobé streamované provádění s kontrolou životního cyklu.\n\n**Jak to OmniRoute řeší:**\n\n- Koncový bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamování SSE s šířením stavu terminálu\n- Rozhraní API životního cyklu úloh pro `tasks/get` a `tasks/cancel`\n\n<details>\n<summary><b>🛰️ 19. „Potřebuji skutečný stav procesu MCP, ne odhadovaný stav.“</b></summary>\n</details>\n\nProvozní týmy potřebují vědět, zda je MCP skutečně aktivní, nejen zda je API dosažitelné.\n\n**Jak to OmniRoute řeší:**\n\n- Soubor běhového heartbeatu s PID, časovými razítky, transportem, počtem nástrojů a režimem rozsahu\n- API stavu MCP kombinující prezenční signál a nedávnou aktivitu\n- Karty stavu uživatelského rozhraní pro zobrazení aktuálnosti procesů/provozuschopnosti/prezenčního signálu\n\n<details>\n<summary><b>📋 20. „Potřebuji auditovatelné provedení nástroje MCP“</b></summary>\n</details>\n\nKdyž nástroje mění konfiguraci nebo spouštějí operační akce, týmy potřebují forenzní sledovatelnost.\n\n**Jak to OmniRoute řeší:**\n\n- Protokolování auditu pro volání nástrojů MCP s podporou SQLite\n- Filtruje podle nástroje, úspěchu/neúspěchu, klíče API a stránkování\n- Tabulka auditu dashboardu + koncové body statistik pro automatizaci\n\n<details>\n<summary><b>🔐 21. „Potřebuji omezená oprávnění MCP pro každou integraci.“</b></summary>\n</details>\n\nRůzní klienti by měli mít přístup ke kategoriím nástrojů s nejnižšími oprávněními.\n\n**Jak to OmniRoute řeší:**\n\n- 9 detailních MCP sond pro kontrolovaný přístup k nástrojům\n- Vynucení rozsahu a viditelnost v uživatelském rozhraní správy MCP\n- Bezpečná výchozí poloha pro provozní nástroje\n\n<details>\n<summary><b>⚙️ 22. „Potřebuji provozní kontroly bez nutnosti přesouvání“</b></summary>\n</details>\n\nTýmy potřebují rychlé změny v běhovém prostředí během incidentů nebo nákladových událostí.\n\n**Jak to OmniRoute řeší:**\n\n- Přepněte aktivaci komba přímo z řídicího panelu MCP\n- Používejte profily odolnosti z předdefinovaných balíčků zásad\n- Resetujte stav jističe ze stejného ovládacího panelu\n\n<details>\n<summary><b>🔄 23. „Potřebuji živý přehled o životním cyklu úkolů A2A a jejich zrušení.“</b></summary>\n</details>\n\nBez přehledu o životním cyklu je obtížné třídit incidenty úkolů.\n\n**Jak to OmniRoute řeší:**\n\n- Výpis/filtrování úkolů podle státu/dovednosti s stránkováním\n- Podrobný přehled metadat úloh, událostí a artefaktů\n- Koncový bod zrušení úlohy a akce uživatelského rozhraní s potvrzením\n\n<details>\n<summary><b>🌊 24. „Potřebuji metriky aktivního streamu pro A2A zátěž“</b></summary>\n</details>\n\nStreamovací pracovní postupy vyžadují provozní přehled o souběžnosti a živých připojeních.\n\n**Jak to OmniRoute řeší:**\n\n- Čítače aktivních streamů integrované do stavu A2A\n- Časové razítko posledního úkolu a počty pro jednotlivé stavy\n- Karty A2A dashboardu pro monitorování provozu v reálném čase\n\n<details>\n<summary><b>🪪 25. „Potřebuji standardní vyhledávání agentů pro klienty“</b></summary>\n</details>\n\nExterní klienti a orchestratoři potřebují pro onboarding strojově čitelná metadata.\n\n**Jak to OmniRoute řeší:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazené v uživatelském rozhraní pro správu\n- API pro stav A2A zahrnuje metadata pro zjišťování pro automatizaci\n\n<details>\n<summary><b>🧭 26. „Potřebuji v uživatelském rozhraní produktu zjistitelnost protokolu.“</b></summary>\n</details>\n\nPokud uživatelé nemohou objevit protokolové povrchy, kvalita přijetí a podpory klesá.\n\n**Jak to OmniRoute řeší:**\n\n- Stránka Konsolidované **koncové body** s kartami pro koncové body Proxy, MCP, A2A a API\n- Přepínání stavu inline služby (Online/Offline) pro MCP a A2A\n- Odkazy z přehledu na vyhrazené karty pro správu\n\n<details>\n<summary><b>🧪 27. „Potřebuji komplexní ověření protokolu se skutečnými klienty.“</b></summary>\n</details>\n\nSimulované testy nestačí k ověření kompatibility protokolu před vydáním.\n\n**Jak to OmniRoute řeší:**\n\n- Sada E2E, která spouští aplikaci a používá skutečný transport klienta MCP SDK.\n- Klientské testy A2A pro toky zjišťování, odesílání, streamování, načítání a zrušení\n- Křížová kontrola tvrzení oproti API pro audit MCP a úkoly A2A\n\n<details>\n<summary><b>📡 28. „Potřebuji jednotnou pozorovatelnost napříč všemi rozhraními“</b></summary>\n</details>\n\nRozdělení pozorovatelnosti podle protokolu vytváří slepá místa a delší MTTR.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocené dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie požadavků napříč vrstvami OpenAI, MCP a A2A\n- Provozní API pro stav a automatizaci\n\n<details>\n<summary><b>💼 29. „Potřebuji jeden runtime pro proxy + nástroje + orchestraci agentů“</b></summary>\n</details>\n\nSpouštění mnoha samostatných služeb zvyšuje provozní náklady a počet poruch.\n\n**Jak to OmniRoute řeší:**\n\n- Proxy, MCP server a A2A server kompatibilní s OpenAI v jednom balíčku\n- Sdílené ověřování, odolnost, úložiště dat a pozorovatelnost\n- Konzistentní model politik napříč všemi interakčními plochami\n\n<details>\n<summary><b>🚀 30. „Potřebuji agentské pracovní postupy bez slepení kódu.“</b></summary>\n</details>\n\nTýmy ztrácejí rychlost při spojování více ad-hoc služeb a skriptů.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocená strategie koncových bodů pro klienty a agenty\n- Vestavěná uživatelská rozhraní pro správu protokolů a cesty pro ověřování kouře\n- Základy připravené pro produkční prostředí (zabezpečení, protokolování, odolnost, zálohování)\n\n### Příklady herních plánů (integrované případy užití)\n\n**Příručka A: Maximalizace placeného předplatného + levné zálohování**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Příručka B: Kódovací stack s nulovými náklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Příručka C: Nonstop záložní řetězec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Příručka D: Operace agentů s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Začněte zdarma — Nulové náklady na konfiguraci\n\n> Nastavte si kódování s umělou inteligencí během několika minut za **0 $/měsíc** . Propojte tyto bezplatné účty a využijte vestavěnou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelé odemčeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Připojení **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 – **neomezeně** |\n| 2 | Připojení k **iFlow** (Google OAuth) | kimi-k2-myšlení, qwen3-coder-plus, deepseek-r1... — **neomezeně** |\n| 3 | Připojení **Qwen** (kód zařízení) | qwen3-coder-plus, qwen3-coder-flash... — **neomezeně** |\n| 4 | Připojení **rozhraní příkazového řádku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180 000 GBP/měsíc zdarma** |\n| 5 | `/dashboard/combos` → Šablona **Free Stack (0 $)** | Automatické zařazení všech bezplatných poskytovatelů do routingu |\n\n**V libovolném IDE/CLI naveďte:** `http://localhost:20128/v1` · Klíč API: `any-string` · Hotovo.\n\n> **Volitelné doplňkové krytí (také zdarma):** Groq API klíč (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelů), Cerebras (1 milion tok/den).\n\n## ⚡ Rychlý start\n\n### 1) Nainstalujte a spusťte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uživatelé pnpm:** Po instalaci spusťte `pnpm approve-builds -g` , abyste povolili nativní skripty pro sestavení vyžadované programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard se otevírá na `http://localhost:20128` a základní URL API je `http://localhost:20128/v1` .\n\n| Příkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuštění serveru ( `PORT=20128` , API a dashboard na stejném portu) |\n| `omniroute --port 3000` | Nastavte kanonický/API port na 3000 |\n| `omniroute --mcp` | Spuštění MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevírat prohlížeč automaticky |\n| `omniroute --help` | Zobrazit nápovědu |\n\nVolitelný režim s rozděleným portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Připojte poskytovatele a vytvořte si klíč API\n\n1. Otevřete Dashboard → `Providers` a připojte alespoň jednoho poskytovatele (klíč OAuth nebo API).\n2. Otevřete Dashboard → `Endpoints` a vytvořte API klíč.\n3. (Volitelné) Otevřete Dashboard → `Combos` a nastavte záložní řetězec.\n\n### 3) Nasměrujte svůj kódovací nástroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilními s OpenAI.\n\n### 4) Povolení a ověření protokolů (v2.0)\n\n**MCP (pro operace řízené nástroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak připojte svého MCP klienta přes `stdio` a otestujte nástroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovní postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ověřte vše od začátku do konce (doporučeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ověřuje skutečné toky klientů MCP a A2A v porovnání se spuštěnou aplikací.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## 🐳 Docker\n\nOmniRoute je k dispozici jako veřejný obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlý běh:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostředí:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Používání Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | Štítek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovější stabilní verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuální verze |\n\n---\n\n## 🖥️ Desktopová aplikace – offline a vždy zapnutá\n\n> 🆕 **NOVINKA!** OmniRoute je nyní k dispozici jako **nativní desktopová aplikace** pro Windows, macOS a Linux.\n\nSpusťte OmniRoute jako samostatnou desktopovou aplikaci – pro lokální modely není potřeba žádný terminál, prohlížeč ani internet. Aplikace založená na platformě Electron obsahuje:\n\n- 🖥️ **Nativní okno** — Vyhrazené okno aplikace s integrací do systémové lišty\n- 🔄 **Automatické spuštění** — Spuštění OmniRoute po přihlášení do systému\n- 🔔 **Nativní oznámení** – Získejte upozornění na vyčerpání kvóty nebo problémy s poskytovateli\n- ⚡ **Instalace jedním kliknutím** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline režim** — Funguje plně offline s přiloženým serverem\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systémový zásobník\n\nPo minimalizaci se OmniRoute nachází v systémové liště a nabízí rychlé akce:\n\n- Otevřít řídicí panel\n- Změnit port serveru\n- Ukončit aplikaci\n\n📖 Úplná dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Přehled cen\n\n| Úroveň | Poskytovatel | Náklady | Obnovení kvóty | Nejlepší pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **💳 PŘEDPLATNÉ** | Claude Code (profesionál) | 20 dolarů měsíčně | 5 hodin + týdně | Již přihlášen/a k odběru |\n| Kodex (Plus/Pro) | 20–200 USD/měsíc | 5 hodin + týdně | Uživatelé OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisíc měsíčně + 1 tisíc denně | Každý! |\n| GitHub Copilot | 10–19 USD/měsíc | Měsíční | Uživatelé GitHubu |\n| **🔑 KLÍČ API** | NVIDIA NIM | **ZDARMA** (vývoj navždy) | ~40 ot./min | 70+ otevřených modelů |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší na světě |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisíc otáček za minutu | Ultrarychlá lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | Žádný | Nejlepší zdůvodnění ceny a kvality |\n| xAI Grok-4 Rychlý | **0,20/0,50 USD za 1 milion** 🆕 | Žádný | Nejrychlejší + volání nástroje, ultranízké |\n| xAI Grok-4 (standardní) | 0,20/1,50 USD za 1 milion 🆕 | Žádný | Vlajková loď Reasoning od xAI |\n| Mistral | Zkušební verze zdarma + placené | Omezená sazba | Evropská umělá inteligence |\n| OpenRouter | Platba za použití | Žádný | Více než 100 modelů agregováno. |\n| **💰 LEVNÉ** | GLM-5 (přes Z.AI) 🆕 | 0,5 USD/1 milion | Denně v 10:00 | Výstup 128 tisíc obrazových bodů, nejnovější vlajková loď |\n| GLM-4.7 | 0,6 USD/1 milion | Denně v 10:00 | Záloha rozpočtu |\n| MiniMax M2.5 🆕 | Vstup 0,3 USD/1 milion | 5hodinové válcování | Úvaha + agentní úkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinové válcování | Nejlevnější varianta |\n| Kimi K2.5 (Moonshot API) 🆕 | Platba za použití | Žádný | Přímý přístup k Moonshot API |\n| Kimi K2 | 9 dolarů měsíčně bez závazků | 10 milionů tokenů/měsíc | Předvídatelné náklady |\n| **🆓 ZDARMA** | iFlow | **0 dolarů** | Neomezený | 5 modelů neomezeně |\n| Qwen | **0 dolarů** | Neomezený | 4 modely neomezeně |\n| Kiro | **0 dolarů** | Neomezený | Claude Sonnet/Haiku (tvorce AWS) |\n\n> 🆕 **Přidány nové modely (březen 2026):** řada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkováno na 1143 ms – o 30 % rychlejší než Gemini 2.5 Flash), GLM-5 přes Z.AI s výstupem 128K, uvažování MiniMax M2.5, aktualizované ceny DeepSeek V3.2, Kimi K2.5 přes Moonshot Direct API.\n\n**💡 Kombinovaný balík za 0 $ — Kompletní bezplatná instalace:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\niFlow (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Nulové náklady. Nikdy nepřestávejte s kódováním.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a všechny záložní režimy se provede automaticky – žádné ruční přepínání.\n\n---\n\n---\n\n## 🆓 Bezplatné modely – Co skutečně získáte\n\n> Všechny níže uvedené modely jsou **100% zdarma a nevyžadují žádnou kreditní kartu** . OmniRoute mezi nimi automaticky propojí trasy, když dojde jedna kvóta – zkombinujte je všechny a získejte tak nerozlučnou kombinaci za 0 dolarů.\n\n### 🔵 CLAUDE MODELS (přes Kiro — AWS Builder ID)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-opus-4.6` | `kr/` | **Neomezený** | Nejnovější opus od Kira |\n\n### 🟢 MODELY IFLOW (Bezplatné OAuth — bez nutnosti platit kreditní kartou)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-plus` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `deepseek-r1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `minimax-m2.1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `kimi-k2` | `if/` | **Neomezený** | Žádný hlášený strop |\n\n### 🟡 MODELY QWEN (Ověření kódu zařízení)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-next` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `vision-model` | `qw/` | **Neomezený** | Multimodální (obrázky) |\n\n### 🟣 Rozhraní GEMINI CLI (Google OAuth)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisíc tok/měsíc** + 1 tisíc/den | Měsíční reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisíc měsíčně (sdílený bazén) | Vysoká kvalita |\n\n### ⚫ NVIDIA NIM (Bezplatný klíč API — build.nvidia.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vývojář) | Žádný limit tokenů | **~40 ot./min** | Více než 70 modelů; přechod na čisté limity sazeb v polovině roku 2025 |\n\nOblíbené bezplatné modely: `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`\n\n### ⚪ CEREBRAS (Bezplatný klíč API — inference.cerebras.ai)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenů/den** | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší inference LLM na světě; denně se resetuje |\n\nDostupné zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Bezplatný API klíč — console.groq.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisíc otáček za minutu** | 30 ot./min na model | Žádná kreditní karta; limit 429, neúčtováno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **💡 Ultimátní bezplatný zásobník:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> → iFlow (5 models, unlimited)\n> → Qwen (4 models, unlimited)\n> → Gemini CLI (180K/mo)\n> → Cerebras (1M tok/day)\n> → Groq (14.4K req/day)\n> → NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a už nikdy nebudete platit za umělou inteligenci.\n\n## 🎙️ Kombinovaná transkripce zdarma\n\n> Přepisujte libovolné audio/video za **0 $** – Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako záložní nástroj, Groq Whisper jako neomezená nouzová záloha.\n\n| Poskytovatel | Bezplatné kredity | Nejlepší model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| 🟢 **Deepgram** | **200 dolarů zdarma** (registrace) | `nova-3` — nejvyšší přesnost, více než 30 jazyků | Žádný limit RPM pro kredity zdarma |\n| 🔵 **AssemblyAI** | **50 dolarů zdarma** (registrace) | `universal-3-pro` — kapitoly, sentiment, osobní údaje | Žádný limit RPM pro kredity zdarma |\n| 🔴 **Groq** | **Navždy zdarma** | `whisper-large-v3` — OpenAI Šepot | 30 ot./min (omezená rychlost) |\n\n**Navrhovaná kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nPak v `/dashboard/media` → záložka **Přepis** : nahrajte libovolný zvukový nebo video soubor → vyberte kombinovaný koncový bod → získejte přepis v podporovaných formátech.\n\n## 💡 Klíčové vlastnosti\n\nOmniRoute v2.0 je navržen jako operační platforma, nikoli pouze jako proxy pro relé.\n\n### 🤖 Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dělá |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **MCP Server (16 nástrojů)** | Nástroje IDE/agent prostřednictvím 3 transportů: stdio, SSE ( `/api/mcp/sse` ), Streamovatelný HTTP ( `/api/mcp/stream` ) |\n| 🤝 **A2A server (JSON-RPC + SSE)** | Spouštění úloh mezi agenty se synchronizací a streamováním |\n| 🧭 **Konsolidovaná stránka koncových bodů** | Stránka pro správu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| 🎚️ **Přepínače pro povolení/zakázání služby** | Přepínače ZAP/VYP pro MCP a A2A s trvalým nastavením (výchozí: VYP) |\n| 🛰️ **Srdeční tep za běhu MCP** | Skutečný stav procesu (pid, doba provozuschopnosti, stáří heartbeatu, transport, režim rozsahu) |\n| 📋 **Auditní záznam MCP** | Filtrovatelné protokoly auditu s hodnocením úspěchu/neúspěchu a klíčovým přiřazením |\n| 🔐 **Vynucování rozsahu MCP** | 9 podrobných oprávnění pro řízený přístup k nástrojům |\n| 📡 **Správa životního cyklu úkolů A2A** | Seznam/filtrování úloh, kontrola událostí/artefaktů, zrušení spuštěných úloh |\n| 📋 **Objevení karty agenta** | `/.well-known/agent.json` pro automatické vyhledávání klientů |\n| 🧪 **Testovací postroj Protocol E2E** | Skutečné MCP SDK + toky klientů A2A v `test:protocols:e2e` |\n| ⚙️ **Provozní kontroly** | Kombinace přepínačů, použití profilů odolnosti, resetování jističů z jednoho ovládacího panelu |\n\n### 🧠 Směrování a inteligence\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| 🎯 **Inteligentní čtyřúrovňový záložní systém** | Automatická trasa: Předplatné → API klíč → Levné → Zdarma |\n| 📊 **Sledování kvót v reálném čase** | Počet tokenů v reálném čase + odpočet resetování pro každého poskytovatele |\n| 🔄 **Překlad formátu** | OpenAI ↔ Claude ↔ Gemini ↔ Odpovědi s konverzemi bezpečnými pro schéma |\n| 👥 **Podpora více účtů** | Více účtů na poskytovatele s inteligentním výběrem |\n| 🔄 **Automatická aktualizace tokenů** | Tokeny OAuth se automaticky obnovují při opakovaném pokusu. |\n| 🎨 **Vlastní kombinace** | 6 vyvažovacích strategií + řízení záložního řetězce |\n| 🌐 **Směrovač se zástupnými znaky** | dynamické směrování `provider/*` |\n| 🧠 **Přemýšlení o rozpočtových kontrolách** | Limity pro průchozí, automatické, vlastní a adaptivní uvažování |\n| 🔀 **Aliasy modelů** | Vestavěné + vlastní aliasování modelů a bezpečnost migrace |\n| ⚡ **Degradace pozadí** | Směrujte úlohy na pozadí s nízkou prioritou na levnější modely |\n| 🧪 **Chytré směrování s ohledem na úkoly** | Automatický výběr modelu podle typu obsahu (kódování/vize/analýza/sumarizace) |\n| 💬 **Vstřikování do systému** | Globální kontroly chování uplatňované konzistentně |\n| 📄 **Kompatibilita API pro odpovědi** | Plná podpora `/v1/responses` pro Codex a pokročilé agentické pracovní postupy |\n\n### 🎵 Multimodální API\n\n| Funkce | Co to dělá |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Generování obrázků** | `/v1/images/generations` s cloudovým a lokálním backendem |\n| 📐 **Vložení** | `/v1/embeddings` pro vyhledávání a RAG pipelines |\n| 🎤 **Přepis zvuku** | `/v1/audio/transcriptions` (Whisper a další poskytovatelé) |\n| 🔊 **Převod textu na řeč** | `/v1/audio/speech` (více enginů/poskytovatelů) |\n| 🎬 **Generování videa** | `/v1/videos/generations` (pracovní postupy ComfyUI + SD WebUI) |\n| 🎵 **Hudební generace** | `/v1/music/generations` (pracovní postupy ComfyUI) |\n| 🛡️ **Moderování** | Bezpečnostní kontroly `/v1/moderations` |\n| 🔀 **Změna pořadí** | `/v1/rerank` pro hodnocení relevance |\n| 🔍 **Vyhledávání na webu** 🆕 | `/v1/search` — 5 poskytovatelů (Serper, Brave, Perplexity, Exa, Tavily), více než 6 500 zdarma/měsíc, automatické přepnutí na záložní systém, mezipaměť |\n\n### 🛡️ Odolnost, bezpečnost a správa věcí veřejných\n\n| Funkce | Co to dělá |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| 🔌 **Jističe** | Vypnutí/obnovení pro každý model s ovládáním prahových hodnot |\n| 🎯 **Modely s ohledem na koncové body** | Vlastní modely deklarují podporované koncové body + formát API |\n| 🛡️ **Stádo proti hromům** | Ochrana mutexu a semaforu při událostech opakování/rychlosti |\n| 🧠 **Sémantická + podpisová mezipaměť** | Snížení nákladů/latence díky dvěma vrstvám mezipaměti |\n| ⚡ **Žádost o idempotenci** | Okno ochrany proti duplikacím |\n| 🔒 **Falšování otisků prstů pomocí TLS** | Otisk TLS podobný prohlížeči – **snižuje detekci botů a nahlašování účtů** |\n| 🔏 **Porovnávání otisků prstů v CLI** | Shoduje se s nativními podpisy požadavků CLI – **snižuje riziko zablokování a zároveň zachovává IP adresu proxy** |\n| 🌐 **Filtrování IP adres** | Ovládání seznamu povolených/blokovaných položek pro odhalená nasazení |\n| 📊 **Upravitelné limity rychlosti** | Konfigurovatelné globální/na úrovni poskytovatele limity s perzistencí |\n| 🔑 **Správa klíčů API a stanovení rozsahu** | Bezpečné vydávání/rotace klíčů a kontroly modelu/poskytovatele |\n| 🛡️ **Chráněné `/models`** | Volitelné ověřování a skrytí poskytovatele pro katalog modelů |\n\n### 📊 Pozorovatelnost a analytika\n\n| Funkce | Co to dělá |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| 📝 **Žádost + protokolování proxy** | Úplné protokolování požadavků/odpovědí a proxy |\n| 📋 **Sjednocený panel protokolů** | Zobrazení požadavků, proxy, auditu a konzole na jedné stránce |\n| 🔍 **Vyžádat si telemetrii** | Latence p50/p95/p99 a trasování požadavků |\n| 🏥 **Panel zdraví** | Doba provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti |\n| 💰 **Sledování nákladů** | Kontrola rozpočtu a přehled o cenách pro jednotlivé modely |\n| 📈 **Analytické vizualizace** | Přehledy využití modelů/poskytovatelů a zobrazení trendů |\n| 🧪 **Rámec hodnocení** | Testování zlaté sady s konfigurovatelnými strategiemi shody |\n\n### ☁️ Nasazení a platforma\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| 🌐 **Nasazení kdekoli** | Localhost, VPS, Docker, cloudová prostředí |\n| 💾 **Synchronizace s cloudem** | Synchronizace konfigurace přes cloud worker |\n| 🔄 **Zálohování/Obnovení** | Toky exportu/importu a obnovy po havárii |\n| 🧙 **Průvodce nástupem** | Průvodce prvním spuštěním |\n| 🔧 **Panel nástrojů CLI** | Nastavení oblíbených kódovacích nástrojů jedním kliknutím |\n| 🎮 **Modelové hřiště** | Otestujte libovolného poskytovatele/model/koncový bod z řídicího panelu |\n| 🔏 **Přepínač otisků prstů v příkazovém řádku** | Porovnávání otisků prstů podle poskytovatele v Nastavení &gt; Zabezpečení |\n| 🌐 **i18n (30 jazyků)** | Plná jazyková podpora dashboardu a dokumentace s psaním zprava doleva |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Adresář vlastních dat** | Přepsání `DATA_DIR` pro umístění úložiště |\n\n### Hluboký pohled na funkce\n\n#### Chytrá záložní funkce s praktickou kontrolou nákladů\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyž selže kvóta, rychlost nebo stav, OmniRoute automaticky přejde k dalšímu kandidátovi bez nutnosti ručního přepínání.\n\n#### Správa protokolů, která je viditelná a ovladatelná\n\n- MCP + A2A jsou viditelné v uživatelském rozhraní a dokumentaci (nejsou skryté)\n- API pro stav protokolu zpřístupňují živá provozní data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnují akce pro operace 2. dne (přepínání kombinací, resetování jističů, zrušení úkolů)\n\n#### Pracovní postup překladatele + validace\n\nOblast překladatele zahrnuje:\n\n- **Hřiště** : kontroly transformace požadavků\n- **Tester chatu** : kompletní okružní cesta požadavku/odpovědi\n- **Testovací stolice** : více případů v jednom běhu\n- **Živý monitor** : zobrazení provozu v reálném čase\n\nPlus validace protokolu se skutečnými klienty pomocí `npm run test:protocols:e2e` .\n\n> 📖 **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** — Referenční informace o nástrojích, konfigurace IDE a příklady klientů\n>\n> 📖 **[Soubor README pro A2A Server](src/lib/a2a/README.md)** — Dovednosti, metody JSON-RPC, streamování a životní cyklus úloh\n\n## 🧪 Hodnocení (Evals)\n\nOmniRoute obsahuje vestavěný hodnotící rámec pro testování kvality odpovědí LLM v porovnání se zlatou sadou. Přístup k němu je možný přes **Analýzy → Hodnocení** v dashboardu.\n\n### Vestavěná zlatá sada\n\nPředinstalovaná sada „OmniRoute Golden Set“ obsahuje testovací případy pro:\n\n- Zdravím, matematika, zeměpis, generování kódu\n- Shoda s formátem JSON, překlad, generování markdownů\n- Bezpečnostní odmítnutí (škodlivý obsah), počítání, booleovská logika\n\n### Strategie hodnocení\n\n| Strategie | Popis | Příklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Výstup se musí přesně shodovat | `\"4\"` |\n| `contains` | Výstup musí obsahovat podřetězec (bez rozlišení velkých a malých písmen) | `\"Paris\"` |\n| `regex` | Výstup musí odpovídat vzoru regulárních výrazů | `\"1.*2.*3\"` |\n| `custom` | Vlastní JS funkce vrací true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Průvodce nastavením\n\n### Nastavení protokolu (MCP + A2A)\n\n<details>\n<summary><b>🧩 Nastavení MCP (Model Context Protocol)</b></summary>\n</details>\n\nSpuštění MCP transportu v režimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporučený postup ověření:\n\n1. Připojte svého MCP klienta přes stdio.\n2. Spusťte `omniroute_get_health` .\n3. Spusťte `omniroute_list_combos` .\n4. Otevřete `/dashboard/mcp` pro ověření prezenčního signálu, aktivity a auditu.\n\nUžitečná API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n<details>\n<summary><b>🤝 Nastavení A2A (Agent2Agent)</b></summary>\n</details>\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat úkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSpráva životního cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvozní uživatelské rozhraní:\n\n- `/dashboard/a2a` pro pozorovatelnost úloh/stavů/streamů a akce kouření\n\n<details>\n<summary><b>🧪 Komplexní validace protokolu</b></summary>\n</details>\n\nOvěřte oba protokoly se skutečnými klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTím se ověřuje:\n\n- Připojení/seznam/volání klienta MCP SDK\n- A2A objevování/odesílání/streamování/získávání/zrušení\n- Křížová kontrola dat v auditu MCP a API pro správu úloh A2A\n\n<details>\n<summary><b>💳 Poskytovatelé předplatného</b></summary>\n</details>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionály:** Pro složité úkoly používejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvótu pro každý model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Správa limitů účtu Codex (5h + týdně)\n\nKaždý účet Codex má nyní přepínače zásad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinového prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zásadu týdenního prahu okna.\n- Prahové chování: když povolené okno dosáhne využití &gt;=90 %, je daný účet přeskočen.\n- Chování rotace: OmniRoute automaticky přesměruje na další způsobilý účet Codex.\n- Chování při resetování: Po `resetAt` určité doby se účet automaticky opět stane způsobilým.\n\nScénáře:\n\n- `5h ON` + `Weekly ON` : účet je přeskočen, když kterékoli z oken dosáhne prahové hodnoty.\n- `5h OFF` + `Weekly ON` : účet může být zablokován pouze týdenním používáním.\n- `5h ON` + `Weekly OFF` : účet může být zablokován pouze při 5hodinovém používání.\n- `resetAt` passed: účet se automaticky znovu zapne (bez ručního opětovného povolení).\n\n### Gemini CLI (ZDARMA 180 000/měsíc!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepší hodnota:** Obrovská bezplatná úroveň! Použijte ji před placenými úrovněmi.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n<details>\n<summary><b>🔑 Poskytovatelé klíčů API</b></summary>\n</details>\n\n### NVIDIA NIM (BEZPLATNÝ přístup pro vývojáře — více než 70 modelů)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Získejte zdarma klíč API (včetně 1000 inferenčních kreditů)\n3. Ovládací panel → Přidat poskytovatele → NVIDIA NIM:\n - Klíč API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a více než 50 dalších\n\n**Tip pro profesionály:** API kompatibilní s OpenAI – funguje bez problémů s překladem formátů OmniRoute!\n\n### Hluboké vyhledávání\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatná úroveň!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Získejte klíč API (včetně bezplatné úrovně)\n3. Ovládací panel → Přidat poskytovatele → Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionály:** Ultrarychlá inference – nejlepší pro kódování v reálném čase!\n\n### OpenRouter (100+ modelů)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → OpenRouter\n\n**Modely:** Získejte přístup k více než 100 modelům od všech hlavních poskytovatelů prostřednictvím jediného klíče API.\n\n<details>\n<summary><b>💰 Levní poskytovatelé (záložní)</b></summary>\n</details>\n\n### GLM-4.7 (Denní reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Získejte klíč API z kódovacího plánu\n3. Nástěnka → Přidat klíč API:\n - Poskytovatel: `glm`\n - Klíč API: `your-key`\n\n**Použití:** `glm/glm-4.7`\n\n**Tip pro profesionály:** Programovací plán nabízí 3× kvótu za cenu 1/7! Obnovuje se denně v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionály:** Nejlevnější varianta pro dlouhý kontext (1 milion tokenů)!\n\n### Kimi K2 (paušální poplatek 9 dolarů měsíčně)\n\n1. Odebírat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `kimi/kimi-latest`\n\n**Tip pro profesionály:** Fixních 9 $/měsíc za 10 milionů tokenů = efektivní náklady 0,90 $/1 milion!\n\n<details>\n<summary><b>🆓 BEZPLATNÍ poskytovatelé (nouzové zálohování)</b></summary>\n</details>\n\n### iFlow (5 BEZPLATNÝCH modelů přes OAuth)\n\n```bash\nDashboard → Connect iFlow\n→ iFlow OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kódem zařízení)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n<details>\n<summary><b>🎨 Vytvořte kombinace</b></summary>\n</details>\n\n### Příklad 1: Maximalizace předplatného → Levné zálohování\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Příklad 2: Pouze zdarma (nulové náklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n<details>\n<summary><b>🔧 Integrace s rozhraním příkazového řádku</b></summary>\n</details>\n\n### IDE kurzoru\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jedním kliknutím použijte stránku **Nástroje CLI** na řídicím panelu nebo ručně upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Možnost 1 – Dashboard (doporučeno):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Možnost 2 – Manuální úprava:** Úprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznámka:** OpenClaw funguje pouze s lokálním OmniRoute. Místo `localhost` použijte `127.0.0.1` , abyste se vyhnuli problémům s rozlišením IPv6.\n\n### Cline / Pokračovat / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Přidání OmniRoute jako vlastního poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvořte/upravte `opencode.json` v kořenovém adresáři projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` přidejte jakýkoli model dostupný ve vašem koncovém bodu OmniRoute `/v1/models` . Použijte formát `provider/model-id` z vašeho dashboardu OmniRoute.\n\n---\n\n## 🐛 Řešení problémů\n\n<details>\n<summary><b>Kliknutím rozbalíte průvodce řešením problémů</b></summary>\n</details>\n\n**\"Jazykový model neposkytoval zprávy\"**\n\n- Kvóta poskytovatele vyčerpána → Zkontrolujte sledování kvót na řídicím panelu\n- Řešení: Použijte záložní kombinovanou variantu nebo přejděte na levnější úroveň\n\n**Omezení rychlosti**\n\n- Kvóta předplatného vyčerpána → Přechod na GLM/MiniMax\n- Přidat kombo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vypršela**\n\n- Automaticky aktualizováno službou OmniRoute\n- Pokud problémy přetrvávají: Ovládací panel → Poskytovatel → Znovu připojit\n\n**Vysoké náklady**\n\n- Zkontrolujte statistiky využití v sekci Nástěnka → Náklady\n- Přepnout primární model na GLM/MiniMax\n- Pro nekritické úlohy použijte bezplatnou úroveň (Gemini CLI, iFlow).\n\n**Porty řídicího panelu/API jsou nesprávné**\n\n- `PORT` je kanonický základní port (a standardně port API)\n- `API_PORT` přepisuje pouze posluchač API kompatibilní s OpenAI.\n- `DASHBOARD_PORT` přepisuje pouze posluchač dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaši veřejnou URL adresu řídicího panelu (pro zpětná volání OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ověřte, zda `BASE_URL` odkazuje na vaši spuštěnou instanci.\n- Ověřte, zda `CLOUD_URL` odkazuje na váš očekávaný cloudový koncový bod.\n- Udržujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na straně serveru.\n\n**První přihlášení nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud není nastaveno, záložní heslo je `123456`\n\n**Žádné protokoly požadavků**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test připojení ukazuje „Neplatné“ pro poskytovatele kompatibilní s OpenAI**\n\n- Mnoho poskytovatelů nezpřístupňuje koncový bod `/models`\n- OmniRoute v1.0.6+ zahrnuje záložní ověření pomocí dokončení chatu\n- Zajistěte, aby základní URL adresa obsahovala příponu `/v1`\n\n### 🔐 OAuth na vzdáleném serveru\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Důležité pro uživatele, kteří provozují OmniRoute na VPS, Dockeru nebo jakémkoli vzdáleném serveru**\n\n#### Proč selhává OAuth v rozhraní CLI Antigravity / Gemini na vzdálených serverech?\n\nPoskytovatelé rozhraní CLI **Antigravity** a **Gemini** používají **Google OAuth 2.0** . Google vyžaduje, aby se `redirect_uri` v toku OAuth přesně shodoval s jedním z předregistrovaných URI v konzoli Google Cloud Console aplikace.\n\nPřihlašovací údaje OAuth, které jsou součástí OmniRoute, jsou registrovány **pouze pro `localhost`** . Když přistupujete k OmniRoute na vzdáleném serveru (např. `https://omniroute.myserver.com` ), Google odmítne ověření pomocí:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Řešení: Nakonfigurujte si vlastní přihlašovací údaje OAuth\n\nV Google Cloud Console je potřeba vytvořit **ID klienta OAuth 2.0** s URI vašeho serveru.\n\n#### Krok za krokem\n\n**1. Otevřete konzoli Google Cloud**\n\nPřejděte na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvořte nové ID klienta OAuth 2.0**\n\n- Klikněte na **„+ Vytvořit přihlašovací údaje“** → **„ID klienta OAuth“**\n- Typ aplikace: **„Webová aplikace“**\n- Název: cokoli chcete (např. `OmniRoute Remote` )\n\n**3. Přidejte autorizované URI pro přesměrování**\n\nDo pole **„Autorizované identifikátory URI pro přesměrování“** přidejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraďte `your-server.com` doménou nebo IP adresou vašeho serveru (v případě potřeby uveďte i port, např. `http://45.33.32.156:20128/callback` ).\n\n**4. Uložte a zkopírujte přihlašovací údaje**\n\nPo vytvoření Google zobrazí **ID klienta** a **tajný kód klienta** .\n\n**5. Nastavení proměnných prostředí**\n\nVe vašem souboru `.env` (nebo proměnných prostředí Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu připojit**\n\nŘídicí panel → Poskytovatelé → Antigravity (nebo Gemini CLI) → OAuth\n\nGoogle nyní bude správně přesměrovávat na `https://your-server.com/callback` .\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nPokud si teď nechcete nastavovat vlastní přihlašovací údaje, můžete stále použít **ruční postup pro URL** :\n\n1. OmniRoute otevírá autorizační URL od Googlu\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru).\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče (i když se stránka nenačte)\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute.\n5. Klikněte na **„Připojit“**\n\n> To funguje, protože autorizační kód v URL adrese je platný bez ohledu na to, zda se načetla přesměrovací stránka.\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nChcete-li získat přístup k přihlašovacím údajům bez vlastní konfigurace, můžete použít následující postup:\n\n1. OmniRoute otevře URL autorizace Google\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru)\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute\n5. Klikněte na **„Připojit\"**\n\n> Toto řešení funguje, protože autorizační kód v URL adrese je platný bez ohledu na načtení přesměrovací stránky.\n\n---\n\n## 🛠️ Technologický stack\n\n<details>\n<summary><b>Kliknutím rozbalíte podrobnosti o technologickém stacku</b></summary>\n</details>\n\n- **Runtime** : Node.js 18–22 LTS (⚠️ Node.js 24+ **není podporován** — nativní binární soubory `better-sqlite3` jsou nekompatibilní)\n- **Jazyk** : TypeScript 5.9 — **100% TypeScript** napříč `src/` a `open-sse/` ( `any` v základních modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databáze** : LowDB (JSON) + SQLite (stav domény + protokoly proxy + audit MCP + rozhodnutí o směrování)\n- **Schémata** : Zod (validace I/O nástrojů MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamování** : Události odeslané serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klíče + autorizace s rozsahem MCP\n- **Testování** : Node.js test runner + Vitest (900+ testů včetně unit, integračních, E2E)\n- **CI/CD** : Akce GitHubu (automatické publikování v npm + Docker Hub při vydání)\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **Balíček** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistič, exponenciální odstavení, ochrana proti hromům, falešné TLS, automatické kombinované samoopravování\n\n---\n\n## 📖 Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uživatelská příručka](docs/USER_GUIDE.md) | Poskytovatelé, kombinace, integrace CLI, nasazení |\n| [Referenční informace k API](docs/API_REFERENCE.md) | Všechny koncové body s příklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nástrojů MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamování, správa úloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorové bodování, balíčky režimů, samoléčba |\n| [Odstraňování problémů](docs/TROUBLESHOOTING.md) | Běžné problémy a jejich řešení |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a interní prvky systému |\n| [Přispívání](CONTRIBUTING.md) | Nastavení a pokyny pro vývoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpečnostní zásady](SECURITY.md) | Hlášení zranitelností a bezpečnostní postupy |\n| [Nasazení virtuálního počítače](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletní průvodce: Nastavení virtuálního počítače + nginx + Cloudflare |\n| [Galerie funkcí](docs/FEATURES.md) | Vizuální prohlídka řídicího panelu se snímky obrazovky |\n| [Kontrolní seznam vydání](docs/RELEASE_CHECKLIST.md) | Kroky ověření před vydáním |\n\n---\n\n## 🗺️ Plán\n\nOmniRoute má **v plánu více než 210 funkcí** v několika fázích vývoje. Zde jsou klíčové oblasti:\n\n| Kategorie | Plánované funkce | Hlavní body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| 🧠 **Směrování a inteligence** | 25+ | Směrování s nejnižší latencí, směrování založené na tagech, kontrola kvót před výstupem, výběr účtu P2C |\n| 🔒 **Zabezpečení a dodržování předpisů** | 20+ | Zpevnění SSRF, maskování přihlašovacích údajů, limit rychlosti pro každý koncový bod, stanovení rozsahu klíčů pro správu |\n| 📊 **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledování kvót v reálném čase, sledování nákladů podle modelu |\n| 🔄 **Integrace poskytovatelů** | 20+ | Dynamický registr modelů, doba zchlazení poskytovatelů, Codex pro více účtů, analýza kvót Copilota |\n| ⚡ **Výkon** | 15+ | Dvojitá vrstva mezipaměti, mezipaměť výzev, mezipaměť odpovědí, udržování streamování, dávkové API |\n| 🌐 **Ekosystém** | 10+ | WebSocket API, horké opětovné načítání konfigurace, distribuované úložiště konfigurace, komerční režim |\n\n### 🔜 Již brzy\n\n- 🔗 **Integrace OpenCode** — Nativní podpora poskytovatelů pro IDE kódování s AI v OpenCode\n- 🔗 **Integrace TRAE** — Plná podpora vývojového rámce TRAE pro umělou inteligenci\n- 📦 **Dávkové API** — Asynchronní dávkové zpracování hromadných požadavků\n- 🎯 **Směrování na základě tagů** — Směrování požadavků na základě vlastních tagů a metadat\n- 💰 **Strategie nejnižších nákladů** – Automaticky vybere nejlevnějšího dostupného poskytovatele\n\n> 📝 Úplné specifikace funkcí jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobných specifikací)\n\n---\n\n## 👥 Přispěvatelé\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Přispěvatelé](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak přispět\n\n1. Vytvoření forku repozitáře\n2. Vytvořte si vlastní větev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrďte změny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do větve ( `git push origin feature/amazing-feature` )\n5. Otevřít žádost o změny (pull request)\n\nPodrobné pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydání nové verze\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Hvězdná historie\n\n## Hvězdáři v průběhu času\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvězdáři v průběhu času](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## 🙏 Poděkování\n\nZvláštní poděkování patří **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** – původnímu projektu, který inspiroval tento fork. OmniRoute staví na tomto neuvěřitelném základu s dalšími funkcemi, multimodálními API a kompletním přepsáním TypeScriptu.\n\nZvláštní poděkování patří **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – původní implementaci Go, která inspirovala tento JavaScriptový port.\n\n---\n\n## 📄 Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n<div align=\"center\">\n <sub>Vytvořeno s ❤️ pro vývojáře, kteří programují 24 hodin denně, 7 dní v týdnu</sub>\n <br>\n <sub><p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\">omniroute.online</a></p></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "88705bb6e97969fa101d0a49fa035a791a5e3bdb": {"t": 1785764466.182805, "n": 91323, "h": "843e088bf02ee23c", "c": "# 🚀 OmniRoute — Bezplatná brána umělé inteligence\n\n### Nikdy nepřestávejte s kódováním. Chytré směrování k **BEZPLATNÝM a levným modelům AI** s automatickým přepínáním mezi záložními systémy.\n\n_Váš univerzální API proxy – jeden endpoint, více než 44 poskytovatelů, nulové výpadky. Nyní s orchestrací agentů **MCP a A2A** ._\n\n**Dokončení chatu • Vkládání • Generování obrázků • Video • Hudba • Audio • Změna pořadí • **Vyhledávání na webu** • MCP server • A2A protokol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n</div>\n<p data-md-type=\"paragraph\"><a href=\"https://www.npmjs.com/package/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/npm/v/omniroute?color=cb3837&amp;logo=npm\" alt=\"verze npm\" data-md-type=\"image\"><a href=\"https://hub.docker.com/r/diegosouzapw/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&amp;logo=docker&amp;color=2496ED\" alt=\"Docker Hub\" data-md-type=\"image\"><a href=\"https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/github/license/diegosouzapw/OmniRoute\" alt=\"Licence\" data-md-type=\"image\"><a href=\"https://omniroute.online\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&amp;logoColor=white\" alt=\"Webové stránky\" data-md-type=\"image\"><a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&amp;logoColor=white\" alt=\"WhatsApp\" data-md-type=\"image\"></p>\n<p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\" data-md-type=\"link\">🌐 Webové stránky</a> • <a href=\"#-quick-start\" data-md-type=\"link\">🚀 Rychlý start</a> • <a href=\"#-key-features\" data-md-type=\"link\">💡 Funkce</a> • <a href=\"#-documentation\" data-md-type=\"link\">📖 Dokumentace</a> • <a href=\"#-pricing-at-a-glance\" data-md-type=\"link\">💰 Ceník</a> • <a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\">💬 WhatsApp</a></p>\n<div data-md-type=\"block_html\"></div>\n\n🌐 **Dostupné v:** 🇺🇸 [Angličtina](README.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [maďarština](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonésie](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nizozemsko](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)\n\n---\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| --- | --- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| --- | --- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n\n\n## 🖼️ Hlavní ovládací panel\n\n<div align=\"center\"> <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"Řídicí panel OmniRoute\" width=\"800\"> </div>\n\n---\n\n## 📸 Náhled řídicího panelu\n\n<details>\n<summary><b>Kliknutím zobrazíte snímky obrazovky z řídicího panelu</b></summary>\n</details>\n\n| Strana | Snímek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelé** | ![Poskytovatelé](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdraví** | ![Zdraví](docs/screenshots/04-health.png) |\n| **Překladatel** | ![Překladatel](docs/screenshots/05-translator.png) |\n| **Nastavení** | ![Nastavení](docs/screenshots/06-settings.png) |\n| **Nástroje CLI** | ![Nástroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly používání** | ![Používání](docs/screenshots/08-usage.png) |\n| **Koncové body** | ![Koncové body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### 🤖 Bezplatný poskytovatel umělé inteligence pro vaše oblíbené programátory\n\n_Připojte libovolný nástroj IDE nebo CLI s umělou inteligencí přes OmniRoute — bezplatnou API bránu pro neomezené kódování._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openclaw/openclaw\"><img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"><br><b>OpenClaw</b></a><br> <sub>⭐ 205 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/HKUDS/nanobot\"><img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"><br><b>NanoBot</b></a><br> <sub>⭐ 20,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/sipeed/picoclaw\"><img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"><br><b>PicoClaw</b></a><br> <sub>⭐ 14,6 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/zeroclaw-labs/zeroclaw\"><img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"><br><b>ZeroClaw</b></a><br> <sub>⭐ 9,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/nearai/ironclaw\"><img src=\"./public/providers/ironclaw.png\" alt=\"Železný dráp\" width=\"48\"><br><b>Železný dráp</b></a><br> <sub>⭐ 2,1 tisíce</sub> </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anomalyco/opencode\"><img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"><br><b>OpenCode</b></a><br> <sub>⭐ 106 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openai/codex\"><img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"><br><b>Codex CLI</b></a><br> <sub>⭐ 60,8 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anthropics/claude-code\"><img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"><br><b>Claude Code</b></a><br> <sub>⭐ 67,3 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/google-gemini/gemini-cli\"><img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"><br> <b>Gemini CLI</b></a><br> <sub>⭐ 94,7 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/Kilo-Org/kilocode\"><img src=\"./public/providers/kilocode.png\" alt=\"Kilo kód\" width=\"48\"><br><b>Kilo kód</b></a><br> <sub>⭐ 15,5 tisíc</sub> </td>\n </tr>\n </table>\n\n<sub>📡 Všichni agenti se připojují přes <code>http://localhost:20128/v1</code> nebo <code>http://cloud.omniroute.online/v1</code> — jedna konfigurace, neomezené modely a kvóty</sub>\n\n---\n\n## 🤔 Proč OmniRoute?\n\n**Přestaňte plýtvat penězi a narážet na limity:**\n\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Kvóta předplatného vyprší každý měsíc\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Limity rychlosti vám zabrání v kódování\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Drahá API (20–50 USD/měsíc na poskytovatele)\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Ruční přepínání mezi poskytovateli\n\n**OmniRoute to řeší:**\n\n- ✅ **Maximalizujte předplatné** – Sledujte kvótu, využijte každou částku před resetováním\n- ✅ **Automatické záložní** – Předplatné → API klíč → Levné → Zdarma, žádné výpadky\n- ✅ **Více účtů** – Round-robin mezi účty u jednotlivých poskytovatelů\n- ✅ **Univerzální** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakýmkoli nástrojem CLI\n\n---\n\n## 📧 Podpora\n\n> 💬 **Přidejte se k naší komunitě!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získejte pomoc, sdílejte tipy a buďte v obraze.\n\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problémy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitní skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Přispívání** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevřete žádost o příspěvek nebo si vyberte `good first issue`\n- **Původní projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### 🐛 Hlásíte chybu?\n\nPři otevírání problému spusťte příkaz system-info a přiložte vygenerovaný soubor:\n\n```bash\nnpm run system-info\n```\n\nTím se vygeneruje soubor `system-info.txt` s verzí Node.js, verzí OmniRoute, podrobnostmi o operačním systému, nainstalovanými nástroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systémovými balíčky – vše, co potřebujeme k rychlé reprodukci vašeho problému. Soubor přiložte přímo k vašemu problému na GitHubu.\n\n---\n\n## 🔄 Jak to funguje\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 Co řeší OmniRoute — 30 skutečných problémů a případů použití\n\n> **Každý vývojář používající nástroje umělé inteligence se s těmito problémy setkává denně.** OmniRoute byl vytvořen tak, aby je všechny vyřešil – od překročení nákladů po regionální bloky, od nefunkčních toků OAuth až po operace s protokoly a sledovatelnost v podniku.\n\n<details>\n<summary><b>💸 1. „Platím si drahé předplatné, ale stále mě ruší limity“</b></summary>\n</details>\n\nVývojáři platí za Claude Pro, Codex Pro nebo GitHub Copilot 20–200 dolarů měsíčně. I při platbě má kvóta strop – 5 hodin používání, týdenní limity nebo limity rychlosti za minutu. Uprostřed kódovací relace poskytovatel přestane reagovat a vývojář ztrácí plynulost a produktivitu.\n\n**Jak to OmniRoute řeší:**\n\n- **Inteligentní čtyřúrovňová záložní služba** – Pokud dojde kvóta předplatného, ​​automaticky se přesměruje na API klíč → Levné → Zdarma bez manuálního zásahu\n- **Sledování kvót v reálném čase** – Zobrazuje spotřebu tokenů v reálném čase s odpočítáváním resetování (5 hodin, denně, týdně)\n- **Podpora více účtů** – Více účtů u jednoho poskytovatele s automatickým přepínáním – když jeden dojde, přepne se na další\n- **Vlastní kombinace** — Přizpůsobitelné záložní řetězce se 6 strategiemi vyvažování (fill-first, round robin, P2C, náhodné, nejméně používané, nákladově optimalizované)\n- **Codex Business Quotas** — Sledování kvót pracovního prostoru firmy/týmu přímo v dashboardu\n\n<details>\n<summary><b>🔌 2. „Potřebuji použít více poskytovatelů, ale každý má jiné API“</b></summary>\n</details>\n\nOpenAI používá jeden formát, Claude (Anthropic) jiný a Gemini ještě třetí. Pokud chce vývojář testovat modely od různých poskytovatelů nebo mezi nimi přecházet, musí překonfigurovat SDK, změnit koncové body a vypořádat se s nekompatibilními formáty. Vlastní poskytovatelé (FriendLI, NIM) mají nestandardní koncové body modelů.\n\n**Jak to OmniRoute řeší:**\n\n- **Sjednocený koncový bod** — Jeden `http://localhost:20128/v1` slouží jako proxy pro všech 67+ poskytovatelů.\n- **Překlad formátu** — Automatický a transparentní: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Sanitizace odpovědí** — Odstraňuje nestandardní pole ( `x_groq` , `usage_breakdown` , `service_tier` ), která porušují OpenAI SDK v1.83+\n- **Normalizace rolí** — Převádí `developer` → `system` pro poskytovatele bez OpenAI; `system` → `user` pro GLM/ERNIE\n- **Extrakce tagů Think** — Extrahuje bloky `<think>` z modelů, jako je DeepSeek R1, do standardizovaného `reasoning_content`\n- **Strukturovaný výstup pro Gemini** — `json_schema` → automatická konverze `responseMimeType` / `responseSchema`\n- **Výchozí hodnota `stream` je `false`** – Odpovídá specifikaci OpenAI, čímž se zabrání neočekávanému SSE v Python/Rust/Go SDK.\n\n<details>\n<summary><b>🌐 3. „Můj poskytovatel AI blokuje můj region/zemi“</b></summary>\n</details>\n\nPoskytovatelé jako OpenAI/Codex blokují přístup z určitých geografických oblastí. Uživatelé se během připojení OAuth a API dostávají k chybám jako `unsupported_country_region_territory` . To je obzvláště frustrující pro vývojáře z rozvojových zemí.\n\n**Jak to OmniRoute řeší:**\n\n- **3úrovňová konfigurace proxy** – Konfigurovatelná proxy na 3 úrovních: globální (veškerý provoz), pro jednotlivé poskytovatele (pouze jeden poskytovatel) a pro jednotlivé připojení/klíč\n- **Barevně kódované odznaky proxy** – Vizuální indikátory: 🟢 globální proxy, 🟡 proxy poskytovatele, 🔵 proxy připojení, vždy zobrazující IP adresu\n- **Výměna tokenů OAuth prostřednictvím proxy** – tok OAuth také prochází přes proxy, čímž se řeší `unsupported_country_region_territory`\n- **Testy připojení přes proxy** – Testy připojení používají nakonfigurovaný proxy (již žádné přímé obcházení)\n- **Podpora SOCKS5** — Plná podpora proxy SOCKS5 pro odchozí směrování\n- **TLS Fingerprint Spoofing** — Otisk prstu TLS podobný prohlížeči pomocí `wreq-js` pro obcházení detekce botů\n- **🔏 Porovnávání otisků prstů v CLI** — Změní pořadí záhlaví a polí v těle serveru tak, aby odpovídala nativním binárním podpisům v CLI, čímž drasticky snižuje riziko nahlašování účtu. IP adresa proxy je zachována — získáte současně stealth **i** maskování IP adresy.\n\n<details>\n<summary><b>🆓 4. „Chci používat umělou inteligenci pro kódování, ale nemám peníze“</b></summary>\n</details>\n\nNe každý si může dovolit zaplatit 20–200 dolarů měsíčně za předplatné AI. Studenti, vývojáři z rozvíjejících se zemí, amatéři a freelanceři potřebují přístup ke kvalitním modelům za nulovou cenu.\n\n**Jak to OmniRoute řeší:**\n\n- **Vestavění poskytovatelé bezplatné úrovně** — Nativní podpora pro 100% bezplatné poskytovatele: iFlow (5 neomezených modelů přes OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezené modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisíc tokenů/měsíc zdarma)\n- **Ollama Cloud** — Cloudově hostované modely Ollama na `api.ollama.com` s bezplatnou úrovní „Light usage“; použijte prefix `ollamacloud/<model>`\n- **Kombinace pouze zdarma** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/měsíc s nulovými prostoji\n- **NVIDIA NIM Free Access** — ~40 RPM developerský přístup k více než 70 modelům na build.nvidia.com (přechod z kreditů na čisté limity rychlosti)\n- **Strategie optimalizace nákladů** – Strategie směrování, která automaticky vybere nejlevnějšího dostupného poskytovatele\n\n<details>\n<summary><b>🔒 5. „Potřebuji chránit svou bránu umělé inteligence před neoprávněným přístupem“</b></summary>\n</details>\n\nPři zpřístupnění brány umělé inteligence síti (LAN, VPS, Docker) může kdokoli s adresou spotřebovat tokeny/kvótu vývojáře. Bez ochrany jsou API zranitelná vůči zneužití, prompt injection a dalšímu zneužití.\n\n**Jak to OmniRoute řeší:**\n\n- **Správa klíčů API** – generování, rotace a vymezování rozsahu pro každého poskytovatele s vyhrazenou stránkou `/dashboard/api-manager`\n- **Oprávnění na úrovni modelu** – Omezení klíčů API na konkrétní modely ( `openai/*` , zástupné znaky) pomocí přepínače Povolit vše/Omezit\n- **Ochrana koncových bodů API** – Vyžaduje klíč pro `/v1/models` a blokuje konkrétní poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** — Všechny trasy dashboardu chráněné middlewarem `withAuth` + tokeny CSRF\n- **Omezovač rychlosti** — Omezování rychlosti na IP s konfigurovatelnými okny\n- **Filtrování IP adres** — Seznam povolených/blokovaných adres pro řízení přístupu\n- **Ochrana proti vkládání výzev** – Sanitizace proti škodlivým vzorcům výzev\n- **Šifrování AES-256-GCM** – přihlašovací údaje jsou v klidovém stavu šifrovány\n\n<details>\n<summary><b>🛑 6. „Můj poskytovatel selhal a já ztratil/a programovací tok“</b></summary>\n</details>\n\nPoskytovatelé umělé inteligence se mohou stát nestabilními, vracet chyby 5xx nebo dosáhnout dočasných limitů rychlosti. Pokud je vývojář závislý na jediném poskytovateli, je jeho práce přerušena. Bez jističů může opakované pokusy vést k pádu aplikace.\n\n**Jak to OmniRoute řeší:**\n\n- **Jistič pro každý model** – Automatické otevírání/zavírání s konfigurovatelnými prahovými hodnotami a dobou ochlazování (Zavřeno/Otevřeno/Poloviční otevření), rozsah definovaný pro každý model, aby se zabránilo kaskádování bloků\n- **Exponenciální odklad** — Progresivní zpoždění opakování\n- **Anti-Thundering Herd** — ochrana Mutex + semafor proti souběžným bouřím s opakovanými pokusy\n- **Kombinované záložní řetězce** – Pokud primární poskytovatel selže, automaticky se propadne řetězcem bez zásahu.\n- **Kombinovaný jistič** – Automaticky deaktivuje selhávajícího poskytovatele v rámci kombinovaného řetězce\n- **Dashboard stavu** — Monitorování provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti, latence p50/p95/p99\n\n<details>\n<summary><b>🔧 7. „Konfigurace každého nástroje umělé inteligence je zdlouhavá a opakující se“</b></summary>\n</details>\n\nVývojáři používají Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Každý nástroj potřebuje jinou konfiguraci (API endpoint, klíč, model). Překonfigurování při změně poskytovatele nebo modelu je ztráta času.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel nástrojů CLI** — Vyhrazená stránka s nastavením jedním kliknutím pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generátor konfigurace GitHub Copilot** – Generuje `chatLanguageModels.json` pro VS Code s hromadným výběrem modelu\n- **Průvodce zaváděním** – 4krokové nastavení pro začínající uživatele\n- **Jeden koncový bod, všechny modely** – jednou nakonfigurujte `http://localhost:20128/v1` a získejte přístup k více než 44 poskytovatelům\n\n<details>\n<summary><b>🔑 8. „Správa OAuth tokenů od více poskytovatelů je peklo“</b></summary>\n</details>\n\nClaude Code, Codex, Gemini CLI, Copilot – všechny používají OAuth 2.0 s tokeny s vypršením platnosti. Vývojáři se musí neustále znovu autentizovat, řešit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdálených serverech. Obzvláště problematický je OAuth v LAN/VPS.\n\n**Jak to OmniRoute řeší:**\n\n- **Automatická aktualizace tokenů** – Tokeny OAuth se obnovují na pozadí před vypršením platnosti.\n- **Vestavěný OAuth 2.0 (PKCE)** – Automatický tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** — Více účtů na poskytovatele prostřednictvím extrakce tokenů JWT/ID\n- **OAuth LAN/Remote Fix** — Detekce privátní IP adresy pro `redirect_uri` + manuální režim URL pro vzdálené servery\n- **OAuth Behind Nginx** — Používá `window.location.origin` pro kompatibilitu s reverzní proxy\n- **Průvodce vzdáleným OAuth** – Podrobný návod k přihlašovacím údajům Google Cloud na VPS/Dockeru\n\n<details>\n<summary><b>📊 9. „Nevím, kolik utrácím ani kde“</b></summary>\n</details>\n\nVývojáři používají více placených poskytovatelů, ale nemají jednotný přehled o výdajích. Každý poskytovatel má svůj vlastní fakturační panel, ale neexistuje žádný konsolidovaný přehled. Mohou se hromadit neočekávané náklady.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard pro analýzu nákladů** – Sledování nákladů na token a správa rozpočtu pro každého poskytovatele\n- **Rozpočtové limity na úroveň** – Strop výdajů na úroveň, který spouští automatický záložní režim\n- **Konfigurace cen podle modelu** – Konfigurovatelné ceny podle modelu\n- **Statistiky použití pro každý klíč API** — Počet požadavků a časové razítko posledního použití pro každý klíč\n- **Analytický panel** – Statistické karty, graf využití modelu, tabulka poskytovatelů s mírou úspěšnosti a latencí\n\n<details>\n<summary><b>🐛 10. „Nedokážu diagnostikovat chyby a problémy ve volání umělé inteligence.“</b></summary>\n</details>\n\nKdyž volání selže, vývojář neví, zda se jednalo o limit rychlosti, vypršelý token, špatný formát nebo chybu poskytovatele. Fragmentované protokoly napříč různými terminály. Bez sledovatelnosti je ladění metodou pokus-omyl.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel jednotných protokolů** – 4 karty: Protokoly požadavků, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlížeč protokolů konzole** — Prohlížeč protokolů v reálném čase ve stylu terminálu s barevně kódovanými úrovněmi, automatickým posouváním, vyhledáváním a filtrováním\n- **Protokoly proxy SQLite** – trvalé protokoly, které přežijí restart serveru\n- **Překladačské hřiště** — 4 režimy ladění: Hřiště (překlad formátu), Tester chatu (okružní), Testovací stůl (dávkový), Živý monitor (v reálném čase)\n- **Telemetrie požadavků** — latence p50/p95/p99 + trasování X-Request-Id\n- **Souborové protokolování s rotací** – Konzolový interceptor zachycuje vše do protokolu JSON s rotací na základě velikosti\n- **Zpráva o systémových informacích** — příkaz `npm run system-info` vygeneruje `system-info.txt` s kompletním popisem vašeho prostředí (verze uzlu, verze OmniRoute, operační systém, nástroje CLI, stav Dockeru/PM2). Přiložte jej při hlášení problémů pro okamžité třídění.\n\n<details>\n<summary><b>🏗️ 11. „Nasazení a údržba brány je složitá“</b></summary>\n</details>\n\nInstalace, konfigurace a údržba AI proxy v různých prostředích (lokální, VPS, Docker, cloud) je pracná. Problémy, jako jsou pevně zakódované cesty, `EACCES` u adresářů, konflikty portů a multiplatformní sestavení, přispívají k obtížím.\n\n**Jak to OmniRoute řeší:**\n\n- **npm globální instalace** — `npm install -g omniroute && omniroute` — hotovo\n- **Docker Multi-Platform** — AMD64 + nativní ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** — `base` (bez nástrojů CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopová aplikace Electron** — Nativní aplikace pro Windows/macOS/Linux se systémovou lištou, automatickým spuštěním a offline režimem\n- **Režim rozdělených portů** – API a řídicí panel na samostatných portech pro pokročilé scénáře (reverzní proxy, síťování kontejnerů)\n- **Cloud Sync** – Konfigurace synchronizace mezi zařízeními pomocí Cloudflare Workers\n- **Zálohy databází** — Automatické zálohování, obnovení, export a import všech nastavení\n\n<details>\n<summary><b>🌍 12. „Rozhraní je pouze v angličtině a můj tým nemluví anglicky“</b></summary>\n</details>\n\nTýmy v neanglicky mluvících zemích, zejména v Latinské Americe, Asii a Evropě, se potýkají s rozhraními pouze v angličtině. Jazykové bariéry snižují míru přijetí a zvyšují chyby v konfiguraci.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard i18n — 30 jazyků** — Všech 500+ kláves je přeloženo včetně arabštiny, bulharštiny, dánštiny, němčiny, španělštiny, finštiny, francouzštiny, hebrejštiny, hindštiny, maďarštiny, indonéštiny, italštiny, japonštiny, korejštiny, malajštiny, holandštiny, norštiny, polštiny, portugalštiny (PT/BR), rumunštiny, ruštiny, slovenštiny, švédštiny, thajštiny, ukrajinštiny, vietnamštiny, čínštiny, filipínštiny a angličtiny\n- **Podpora RTL** – Podpora psaní zprava doleva pro arabštinu a hebrejštinu\n- **Vícejazyčné soubory README** — 30 kompletních překladů dokumentace\n- **Výběr jazyka** — Ikona glóbu v záhlaví pro přepínání v reálném čase\n\n<details>\n<summary><b>🔄 13. „Potřebuji víc než jen chat – potřebuji vložené soubory, obrázky, zvuk.“</b></summary>\n</details>\n\nUmělá inteligence není jen dokončování chatu. Vývojáři potřebují generovat obrázky, přepisovat zvuk, vytvářet embeddedy pro RAG, měnit pořadí dokumentů a moderovat obsah. Každé API má jiný koncový bod a formát.\n\n**Jak to OmniRoute řeší:**\n\n- **Vkládání** — `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generování obrázků** — `/v1/images/generations` s 10 poskytovateli a více než 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Převod textu na video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Převod textu na hudbu** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Přepis zvuku** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Převod textu na řeč** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a další stávající poskytovatelé\n- **Moderování** — `/v1/moderations` — Kontroly bezpečnosti obsahu\n- **Změna pořadí** — `/v1/rerank` — Změna pořadí relevance dokumentu\n- **Responses API** — Plná podpora `/v1/responses` pro Codex\n\n<details>\n<summary><b>🧪 14. „Nemám způsob, jak testovat a porovnávat kvalitu napříč modely.“</b></summary>\n</details>\n\nVývojáři chtějí vědět, který model je pro jejich případ použití nejlepší – kód, překlad, uvažování – ale ruční porovnávání je pomalé. Neexistují žádné integrované nástroje pro vyhodnocování.\n\n**Jak to OmniRoute řeší:**\n\n- **Hodnocení LLM** — Testování Golden setu s 10 předinstalovanými případy zahrnujícími pozdravy, matematiku, geografii, generování kódu, dodržování JSON, překlad, markdown, odmítnutí bezpečnostních požadavků\n- **4 strategie shody** — `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovací lavice pro překladatelské hřiště** — Dávkové testování s více vstupy a očekávanými výstupy, porovnání napříč poskytovateli\n- **Tester chatu** — Kompletní okružní cesta s vizuálním vykreslováním odpovědí\n- **Živý monitor** — Stream všech požadavků procházejících proxy serverem v reálném čase\n\n<details>\n<summary><b>📈 15. „Potřebuji škálovat bez ztráty výkonu“</b></summary>\n</details>\n\nS rostoucím objemem požadavků generují stejné otázky bez ukládání do mezipaměti duplicitní náklady. Bez idempotence duplicitní požadavky plýtvají zpracováním. Je nutné dodržovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute řeší:**\n\n- **Sémantická mezipaměť** — Dvouvrstvá mezipaměť (signatura + sémantika) snižuje náklady a latenci\n- **Idempotence požadavku** — 5s deduplikační okno pro identické požadavky\n- **Detekce limitu rychlosti** – sledování otáček za minutu (RPM), minimální mezera a maximální souběžné sledování pro každého poskytovatele\n- **Upravitelné limity rychlosti** — Konfigurovatelné výchozí hodnoty v Nastavení → Odolnost s perzistencí\n- **Mezipaměť pro ověření klíčů API** — třívrstvá mezipaměť pro výkon produkčního prostředí\n- **Dashboard s telemetrií** – latence p50/p95/p99, statistiky mezipaměti, dostupnost\n\n<details>\n<summary><b>🤖 16. „Chci mít chování modelů globálně pod kontrolou“</b></summary>\n</details>\n\nVývojáři, kteří chtějí všechny odpovědi v určitém jazyce, se specifickým tónem nebo chtějí omezit tokeny pro uvažování. Konfigurace této funkce v každém nástroji/požadavku je nepraktická.\n\n**Jak to OmniRoute řeší:**\n\n- **Vložení systémového prompt** – Globální prompt aplikovaný na všechny požadavky\n- **Validace rozpočtu Thinking** — Řízení alokace tokenů na požadavek (průchozí, automatické, vlastní, adaptivní)\n- **6 strategií směrování** – Globální strategie, které určují, jak jsou požadavky distribuovány\n- **Směrovač se zástupnými znaky** — vzory `provider/*` dynamicky směrují k libovolnému poskytovateli\n- **Přepínání povolení/zakázání kombinací** – Přepínání kombinací přímo z řídicího panelu\n- **Přepínání poskytovatele** – Povolení/zakázání všech připojení pro poskytovatele jedním kliknutím\n- **Blokovaní poskytovatelé** – Vyloučení konkrétních poskytovatelů ze seznamu `/v1/models`\n\n<details>\n<summary><b>🧰 17. „Potřebuji nástroje MCP jako prvotřídní produktové funkce.“</b></summary>\n</details>\n\nMnoho bran umělé inteligence odhaluje MCP pouze jako skrytý implementační detail. Týmy potřebují viditelnou a spravovatelnou operační vrstvu.\n\n**Jak to OmniRoute řeší:**\n\n- MCP se zobrazuje v navigaci na řídicím panelu a na kartě protokolu koncového bodu.\n- Vyhrazená stránka pro správu MCP s procesy, nástroji, rozsahy a auditem\n- Vestavěný rychlý start pro `omniroute --mcp` a onboarding klienta\n\n<details>\n<summary><b>🧠 18. „Potřebuji orchestraci A2A se synchronizací a cestami úloh streamu.“</b></summary>\n</details>\n\nPracovní postupy agentů vyžadují jak přímé odpovědi, tak dlouhodobé streamované provádění s kontrolou životního cyklu.\n\n**Jak to OmniRoute řeší:**\n\n- Koncový bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamování SSE s šířením stavu terminálu\n- Rozhraní API životního cyklu úloh pro `tasks/get` a `tasks/cancel`\n\n<details>\n<summary><b>🛰️ 19. „Potřebuji skutečný stav procesu MCP, ne odhadovaný stav.“</b></summary>\n</details>\n\nProvozní týmy potřebují vědět, zda je MCP skutečně aktivní, nejen zda je API dosažitelné.\n\n**Jak to OmniRoute řeší:**\n\n- Soubor běhového heartbeatu s PID, časovými razítky, transportem, počtem nástrojů a režimem rozsahu\n- API stavu MCP kombinující prezenční signál a nedávnou aktivitu\n- Karty stavu uživatelského rozhraní pro zobrazení aktuálnosti procesů/provozuschopnosti/prezenčního signálu\n\n<details>\n<summary><b>📋 20. „Potřebuji auditovatelné provedení nástroje MCP“</b></summary>\n</details>\n\nKdyž nástroje mění konfiguraci nebo spouštějí operační akce, týmy potřebují forenzní sledovatelnost.\n\n**Jak to OmniRoute řeší:**\n\n- Protokolování auditu pro volání nástrojů MCP s podporou SQLite\n- Filtruje podle nástroje, úspěchu/neúspěchu, klíče API a stránkování\n- Tabulka auditu dashboardu + koncové body statistik pro automatizaci\n\n<details>\n<summary><b>🔐 21. „Potřebuji omezená oprávnění MCP pro každou integraci.“</b></summary>\n</details>\n\nRůzní klienti by měli mít přístup ke kategoriím nástrojů s nejnižšími oprávněními.\n\n**Jak to OmniRoute řeší:**\n\n- 9 detailních MCP sond pro kontrolovaný přístup k nástrojům\n- Vynucení rozsahu a viditelnost v uživatelském rozhraní správy MCP\n- Bezpečná výchozí poloha pro provozní nástroje\n\n<details>\n<summary><b>⚙️ 22. „Potřebuji provozní kontroly bez nutnosti přesouvání“</b></summary>\n</details>\n\nTýmy potřebují rychlé změny v běhovém prostředí během incidentů nebo nákladových událostí.\n\n**Jak to OmniRoute řeší:**\n\n- Přepněte aktivaci komba přímo z řídicího panelu MCP\n- Používejte profily odolnosti z předdefinovaných balíčků zásad\n- Resetujte stav jističe ze stejného ovládacího panelu\n\n<details>\n<summary><b>🔄 23. „Potřebuji živý přehled o životním cyklu úkolů A2A a jejich zrušení.“</b></summary>\n</details>\n\nBez přehledu o životním cyklu je obtížné třídit incidenty úkolů.\n\n**Jak to OmniRoute řeší:**\n\n- Výpis/filtrování úkolů podle státu/dovednosti s stránkováním\n- Podrobný přehled metadat úloh, událostí a artefaktů\n- Koncový bod zrušení úlohy a akce uživatelského rozhraní s potvrzením\n\n<details>\n<summary><b>🌊 24. „Potřebuji metriky aktivního streamu pro A2A zátěž“</b></summary>\n</details>\n\nStreamovací pracovní postupy vyžadují provozní přehled o souběžnosti a živých připojeních.\n\n**Jak to OmniRoute řeší:**\n\n- Čítače aktivních streamů integrované do stavu A2A\n- Časové razítko posledního úkolu a počty pro jednotlivé stavy\n- Karty A2A dashboardu pro monitorování provozu v reálném čase\n\n<details>\n<summary><b>🪪 25. „Potřebuji standardní vyhledávání agentů pro klienty“</b></summary>\n</details>\n\nExterní klienti a orchestratoři potřebují pro onboarding strojově čitelná metadata.\n\n**Jak to OmniRoute řeší:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazené v uživatelském rozhraní pro správu\n- API pro stav A2A zahrnuje metadata pro zjišťování pro automatizaci\n\n<details>\n<summary><b>🧭 26. „Potřebuji v uživatelském rozhraní produktu zjistitelnost protokolu.“</b></summary>\n</details>\n\nPokud uživatelé nemohou objevit protokolové povrchy, kvalita přijetí a podpory klesá.\n\n**Jak to OmniRoute řeší:**\n\n- Stránka Konsolidované **koncové body** s kartami pro koncové body Proxy, MCP, A2A a API\n- Přepínání stavu inline služby (Online/Offline) pro MCP a A2A\n- Odkazy z přehledu na vyhrazené karty pro správu\n\n<details>\n<summary><b>🧪 27. „Potřebuji komplexní ověření protokolu se skutečnými klienty.“</b></summary>\n</details>\n\nSimulované testy nestačí k ověření kompatibility protokolu před vydáním.\n\n**Jak to OmniRoute řeší:**\n\n- Sada E2E, která spouští aplikaci a používá skutečný transport klienta MCP SDK.\n- Klientské testy A2A pro toky zjišťování, odesílání, streamování, načítání a zrušení\n- Křížová kontrola tvrzení oproti API pro audit MCP a úkoly A2A\n\n<details>\n<summary><b>📡 28. „Potřebuji jednotnou pozorovatelnost napříč všemi rozhraními“</b></summary>\n</details>\n\nRozdělení pozorovatelnosti podle protokolu vytváří slepá místa a delší MTTR.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocené dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie požadavků napříč vrstvami OpenAI, MCP a A2A\n- Provozní API pro stav a automatizaci\n\n<details>\n<summary><b>💼 29. „Potřebuji jeden runtime pro proxy + nástroje + orchestraci agentů“</b></summary>\n</details>\n\nSpouštění mnoha samostatných služeb zvyšuje provozní náklady a počet poruch.\n\n**Jak to OmniRoute řeší:**\n\n- Proxy, MCP server a A2A server kompatibilní s OpenAI v jednom balíčku\n- Sdílené ověřování, odolnost, úložiště dat a pozorovatelnost\n- Konzistentní model politik napříč všemi interakčními plochami\n\n<details>\n<summary><b>🚀 30. „Potřebuji agentské pracovní postupy bez slepení kódu.“</b></summary>\n</details>\n\nTýmy ztrácejí rychlost při spojování více ad-hoc služeb a skriptů.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocená strategie koncových bodů pro klienty a agenty\n- Vestavěná uživatelská rozhraní pro správu protokolů a cesty pro ověřování kouře\n- Základy připravené pro produkční prostředí (zabezpečení, protokolování, odolnost, zálohování)\n\n### Příklady herních plánů (integrované případy užití)\n\n**Příručka A: Maximalizace placeného předplatného + levné zálohování**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Příručka B: Kódovací stack s nulovými náklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Příručka C: Nonstop záložní řetězec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Příručka D: Operace agentů s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Začněte zdarma — Nulové náklady na konfiguraci\n\n> Nastavte si kódování s umělou inteligencí během několika minut za **0 $/měsíc** . Propojte tyto bezplatné účty a využijte vestavěnou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelé odemčeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Připojení **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 – **neomezeně** |\n| 2 | Připojení k **iFlow** (Google OAuth) | kimi-k2-myšlení, qwen3-coder-plus, deepseek-r1... — **neomezeně** |\n| 3 | Připojení **Qwen** (kód zařízení) | qwen3-coder-plus, qwen3-coder-flash... — **neomezeně** |\n| 4 | Připojení **rozhraní příkazového řádku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180 000 GBP/měsíc zdarma** |\n| 5 | `/dashboard/combos` → Šablona **Free Stack (0 $)** | Automatické zařazení všech bezplatných poskytovatelů do routingu |\n\n**V libovolném IDE/CLI naveďte:** `http://localhost:20128/v1` · Klíč API: `any-string` · Hotovo.\n\n> **Volitelné doplňkové krytí (také zdarma):** Groq API klíč (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelů), Cerebras (1 milion tok/den).\n\n## ⚡ Rychlý start\n\n### 1) Nainstalujte a spusťte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uživatelé pnpm:** Po instalaci spusťte `pnpm approve-builds -g` , abyste povolili nativní skripty pro sestavení vyžadované programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard se otevírá na `http://localhost:20128` a základní URL API je `http://localhost:20128/v1` .\n\n| Příkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuštění serveru ( `PORT=20128` , API a dashboard na stejném portu) |\n| `omniroute --port 3000` | Nastavte kanonický/API port na 3000 |\n| `omniroute --mcp` | Spuštění MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevírat prohlížeč automaticky |\n| `omniroute --help` | Zobrazit nápovědu |\n\nVolitelný režim s rozděleným portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Připojte poskytovatele a vytvořte si klíč API\n\n1. Otevřete Dashboard → `Providers` a připojte alespoň jednoho poskytovatele (klíč OAuth nebo API).\n2. Otevřete Dashboard → `Endpoints` a vytvořte API klíč.\n3. (Volitelné) Otevřete Dashboard → `Combos` a nastavte záložní řetězec.\n\n### 3) Nasměrujte svůj kódovací nástroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilními s OpenAI.\n\n### 4) Povolení a ověření protokolů (v2.0)\n\n**MCP (pro operace řízené nástroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak připojte svého MCP klienta přes `stdio` a otestujte nástroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovní postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ověřte vše od začátku do konce (doporučeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ověřuje skutečné toky klientů MCP a A2A v porovnání se spuštěnou aplikací.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## 🐳 Docker\n\nOmniRoute je k dispozici jako veřejný obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlý běh:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostředí:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Používání Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | Štítek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovější stabilní verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuální verze |\n\n---\n\n## 🖥️ Desktopová aplikace – offline a vždy zapnutá\n\n> 🆕 **NOVINKA!** OmniRoute je nyní k dispozici jako **nativní desktopová aplikace** pro Windows, macOS a Linux.\n\nSpusťte OmniRoute jako samostatnou desktopovou aplikaci – pro lokální modely není potřeba žádný terminál, prohlížeč ani internet. Aplikace založená na platformě Electron obsahuje:\n\n- 🖥️ **Nativní okno** — Vyhrazené okno aplikace s integrací do systémové lišty\n- 🔄 **Automatické spuštění** — Spuštění OmniRoute po přihlášení do systému\n- 🔔 **Nativní oznámení** – Získejte upozornění na vyčerpání kvóty nebo problémy s poskytovateli\n- ⚡ **Instalace jedním kliknutím** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline režim** — Funguje plně offline s přiloženým serverem\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systémový zásobník\n\nPo minimalizaci se OmniRoute nachází v systémové liště a nabízí rychlé akce:\n\n- Otevřít řídicí panel\n- Změnit port serveru\n- Ukončit aplikaci\n\n📖 Úplná dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Přehled cen\n\n| Úroveň | Poskytovatel | Náklady | Obnovení kvóty | Nejlepší pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **💳 PŘEDPLATNÉ** | Claude Code (profesionál) | 20 dolarů měsíčně | 5 hodin + týdně | Již přihlášen/a k odběru |\n| Kodex (Plus/Pro) | 20–200 USD/měsíc | 5 hodin + týdně | Uživatelé OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisíc měsíčně + 1 tisíc denně | Každý! |\n| GitHub Copilot | 10–19 USD/měsíc | Měsíční | Uživatelé GitHubu |\n| **🔑 KLÍČ API** | NVIDIA NIM | **ZDARMA** (vývoj navždy) | ~40 ot./min | 70+ otevřených modelů |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší na světě |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisíc otáček za minutu | Ultrarychlá lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | Žádný | Nejlepší zdůvodnění ceny a kvality |\n| xAI Grok-4 Rychlý | **0,20/0,50 USD za 1 milion** 🆕 | Žádný | Nejrychlejší + volání nástroje, ultranízké |\n| xAI Grok-4 (standardní) | 0,20/1,50 USD za 1 milion 🆕 | Žádný | Vlajková loď Reasoning od xAI |\n| Mistral | Zkušební verze zdarma + placené | Omezená sazba | Evropská umělá inteligence |\n| OpenRouter | Platba za použití | Žádný | Více než 100 modelů agregováno. |\n| **💰 LEVNÉ** | GLM-5 (přes Z.AI) 🆕 | 0,5 USD/1 milion | Denně v 10:00 | Výstup 128 tisíc obrazových bodů, nejnovější vlajková loď |\n| GLM-4.7 | 0,6 USD/1 milion | Denně v 10:00 | Záloha rozpočtu |\n| MiniMax M2.5 🆕 | Vstup 0,3 USD/1 milion | 5hodinové válcování | Úvaha + agentní úkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinové válcování | Nejlevnější varianta |\n| Kimi K2.5 (Moonshot API) 🆕 | Platba za použití | Žádný | Přímý přístup k Moonshot API |\n| Kimi K2 | 9 dolarů měsíčně bez závazků | 10 milionů tokenů/měsíc | Předvídatelné náklady |\n| **🆓 ZDARMA** | iFlow | **0 dolarů** | Neomezený | 5 modelů neomezeně |\n| Qwen | **0 dolarů** | Neomezený | 4 modely neomezeně |\n| Kiro | **0 dolarů** | Neomezený | Claude Sonnet/Haiku (tvorce AWS) |\n\n> 🆕 **Přidány nové modely (březen 2026):** řada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkováno na 1143 ms – o 30 % rychlejší než Gemini 2.5 Flash), GLM-5 přes Z.AI s výstupem 128K, uvažování MiniMax M2.5, aktualizované ceny DeepSeek V3.2, Kimi K2.5 přes Moonshot Direct API.\n\n**💡 Kombinovaný balík za 0 $ — Kompletní bezplatná instalace:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\niFlow (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Nulové náklady. Nikdy nepřestávejte s kódováním.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a všechny záložní režimy se provede automaticky – žádné ruční přepínání.\n\n---\n\n---\n\n## 🆓 Bezplatné modely – Co skutečně získáte\n\n> Všechny níže uvedené modely jsou **100% zdarma a nevyžadují žádnou kreditní kartu** . OmniRoute mezi nimi automaticky propojí trasy, když dojde jedna kvóta – zkombinujte je všechny a získejte tak nerozlučnou kombinaci za 0 dolarů.\n\n### 🔵 CLAUDE MODELS (přes Kiro — AWS Builder ID)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-opus-4.6` | `kr/` | **Neomezený** | Nejnovější opus od Kira |\n\n### 🟢 MODELY IFLOW (Bezplatné OAuth — bez nutnosti platit kreditní kartou)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-plus` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `deepseek-r1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `minimax-m2.1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `kimi-k2` | `if/` | **Neomezený** | Žádný hlášený strop |\n\n### 🟡 MODELY QWEN (Ověření kódu zařízení)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-next` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `vision-model` | `qw/` | **Neomezený** | Multimodální (obrázky) |\n\n### 🟣 Rozhraní GEMINI CLI (Google OAuth)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisíc tok/měsíc** + 1 tisíc/den | Měsíční reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisíc měsíčně (sdílený bazén) | Vysoká kvalita |\n\n### ⚫ NVIDIA NIM (Bezplatný klíč API — build.nvidia.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vývojář) | Žádný limit tokenů | **~40 ot./min** | Více než 70 modelů; přechod na čisté limity sazeb v polovině roku 2025 |\n\nOblíbené bezplatné modely: `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`\n\n### ⚪ CEREBRAS (Bezplatný klíč API — inference.cerebras.ai)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenů/den** | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší inference LLM na světě; denně se resetuje |\n\nDostupné zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Bezplatný API klíč — console.groq.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisíc otáček za minutu** | 30 ot./min na model | Žádná kreditní karta; limit 429, neúčtováno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **💡 Ultimátní bezplatný zásobník:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> → iFlow (5 models, unlimited)\n> → Qwen (4 models, unlimited)\n> → Gemini CLI (180K/mo)\n> → Cerebras (1M tok/day)\n> → Groq (14.4K req/day)\n> → NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a už nikdy nebudete platit za umělou inteligenci.\n\n## 🎙️ Kombinovaná transkripce zdarma\n\n> Přepisujte libovolné audio/video za **0 $** – Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako záložní nástroj, Groq Whisper jako neomezená nouzová záloha.\n\n| Poskytovatel | Bezplatné kredity | Nejlepší model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| 🟢 **Deepgram** | **200 dolarů zdarma** (registrace) | `nova-3` — nejvyšší přesnost, více než 30 jazyků | Žádný limit RPM pro kredity zdarma |\n| 🔵 **AssemblyAI** | **50 dolarů zdarma** (registrace) | `universal-3-pro` — kapitoly, sentiment, osobní údaje | Žádný limit RPM pro kredity zdarma |\n| 🔴 **Groq** | **Navždy zdarma** | `whisper-large-v3` — OpenAI Šepot | 30 ot./min (omezená rychlost) |\n\n**Navrhovaná kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nPak v `/dashboard/media` → záložka **Přepis** : nahrajte libovolný zvukový nebo video soubor → vyberte kombinovaný koncový bod → získejte přepis v podporovaných formátech.\n\n## 💡 Klíčové vlastnosti\n\nOmniRoute v2.0 je navržen jako operační platforma, nikoli pouze jako proxy pro relé.\n\n### 🤖 Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dělá |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **MCP Server (16 nástrojů)** | Nástroje IDE/agent prostřednictvím 3 transportů: stdio, SSE ( `/api/mcp/sse` ), Streamovatelný HTTP ( `/api/mcp/stream` ) |\n| 🤝 **A2A server (JSON-RPC + SSE)** | Spouštění úloh mezi agenty se synchronizací a streamováním |\n| 🧭 **Konsolidovaná stránka koncových bodů** | Stránka pro správu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| 🎚️ **Přepínače pro povolení/zakázání služby** | Přepínače ZAP/VYP pro MCP a A2A s trvalým nastavením (výchozí: VYP) |\n| 🛰️ **Srdeční tep za běhu MCP** | Skutečný stav procesu (pid, doba provozuschopnosti, stáří heartbeatu, transport, režim rozsahu) |\n| 📋 **Auditní záznam MCP** | Filtrovatelné protokoly auditu s hodnocením úspěchu/neúspěchu a klíčovým přiřazením |\n| 🔐 **Vynucování rozsahu MCP** | 9 podrobných oprávnění pro řízený přístup k nástrojům |\n| 📡 **Správa životního cyklu úkolů A2A** | Seznam/filtrování úloh, kontrola událostí/artefaktů, zrušení spuštěných úloh |\n| 📋 **Objevení karty agenta** | `/.well-known/agent.json` pro automatické vyhledávání klientů |\n| 🧪 **Testovací postroj Protocol E2E** | Skutečné MCP SDK + toky klientů A2A v `test:protocols:e2e` |\n| ⚙️ **Provozní kontroly** | Kombinace přepínačů, použití profilů odolnosti, resetování jističů z jednoho ovládacího panelu |\n\n### 🧠 Směrování a inteligence\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| 🎯 **Inteligentní čtyřúrovňový záložní systém** | Automatická trasa: Předplatné → API klíč → Levné → Zdarma |\n| 📊 **Sledování kvót v reálném čase** | Počet tokenů v reálném čase + odpočet resetování pro každého poskytovatele |\n| 🔄 **Překlad formátu** | OpenAI ↔ Claude ↔ Gemini ↔ Odpovědi s konverzemi bezpečnými pro schéma |\n| 👥 **Podpora více účtů** | Více účtů na poskytovatele s inteligentním výběrem |\n| 🔄 **Automatická aktualizace tokenů** | Tokeny OAuth se automaticky obnovují při opakovaném pokusu. |\n| 🎨 **Vlastní kombinace** | 6 vyvažovacích strategií + řízení záložního řetězce |\n| 🌐 **Směrovač se zástupnými znaky** | dynamické směrování `provider/*` |\n| 🧠 **Přemýšlení o rozpočtových kontrolách** | Limity pro průchozí, automatické, vlastní a adaptivní uvažování |\n| 🔀 **Aliasy modelů** | Vestavěné + vlastní aliasování modelů a bezpečnost migrace |\n| ⚡ **Degradace pozadí** | Směrujte úlohy na pozadí s nízkou prioritou na levnější modely |\n| 🧪 **Chytré směrování s ohledem na úkoly** | Automatický výběr modelu podle typu obsahu (kódování/vize/analýza/sumarizace) |\n| 💬 **Vstřikování do systému** | Globální kontroly chování uplatňované konzistentně |\n| 📄 **Kompatibilita API pro odpovědi** | Plná podpora `/v1/responses` pro Codex a pokročilé agentické pracovní postupy |\n\n### 🎵 Multimodální API\n\n| Funkce | Co to dělá |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Generování obrázků** | `/v1/images/generations` s cloudovým a lokálním backendem |\n| 📐 **Vložení** | `/v1/embeddings` pro vyhledávání a RAG pipelines |\n| 🎤 **Přepis zvuku** | `/v1/audio/transcriptions` (Whisper a další poskytovatelé) |\n| 🔊 **Převod textu na řeč** | `/v1/audio/speech` (více enginů/poskytovatelů) |\n| 🎬 **Generování videa** | `/v1/videos/generations` (pracovní postupy ComfyUI + SD WebUI) |\n| 🎵 **Hudební generace** | `/v1/music/generations` (pracovní postupy ComfyUI) |\n| 🛡️ **Moderování** | Bezpečnostní kontroly `/v1/moderations` |\n| 🔀 **Změna pořadí** | `/v1/rerank` pro hodnocení relevance |\n| 🔍 **Vyhledávání na webu** 🆕 | `/v1/search` — 5 poskytovatelů (Serper, Brave, Perplexity, Exa, Tavily), více než 6 500 zdarma/měsíc, automatické přepnutí na záložní systém, mezipaměť |\n\n### 🛡️ Odolnost, bezpečnost a správa věcí veřejných\n\n| Funkce | Co to dělá |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| 🔌 **Jističe** | Vypnutí/obnovení pro každý model s ovládáním prahových hodnot |\n| 🎯 **Modely s ohledem na koncové body** | Vlastní modely deklarují podporované koncové body + formát API |\n| 🛡️ **Stádo proti hromům** | Ochrana mutexu a semaforu při událostech opakování/rychlosti |\n| 🧠 **Sémantická + podpisová mezipaměť** | Snížení nákladů/latence díky dvěma vrstvám mezipaměti |\n| ⚡ **Žádost o idempotenci** | Okno ochrany proti duplikacím |\n| 🔒 **Falšování otisků prstů pomocí TLS** | Otisk TLS podobný prohlížeči – **snižuje detekci botů a nahlašování účtů** |\n| 🔏 **Porovnávání otisků prstů v CLI** | Shoduje se s nativními podpisy požadavků CLI – **snižuje riziko zablokování a zároveň zachovává IP adresu proxy** |\n| 🌐 **Filtrování IP adres** | Ovládání seznamu povolených/blokovaných položek pro odhalená nasazení |\n| 📊 **Upravitelné limity rychlosti** | Konfigurovatelné globální/na úrovni poskytovatele limity s perzistencí |\n| 🔑 **Správa klíčů API a stanovení rozsahu** | Bezpečné vydávání/rotace klíčů a kontroly modelu/poskytovatele |\n| 🛡️ **Chráněné `/models`** | Volitelné ověřování a skrytí poskytovatele pro katalog modelů |\n\n### 📊 Pozorovatelnost a analytika\n\n| Funkce | Co to dělá |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| 📝 **Žádost + protokolování proxy** | Úplné protokolování požadavků/odpovědí a proxy |\n| 📋 **Sjednocený panel protokolů** | Zobrazení požadavků, proxy, auditu a konzole na jedné stránce |\n| 🔍 **Vyžádat si telemetrii** | Latence p50/p95/p99 a trasování požadavků |\n| 🏥 **Panel zdraví** | Doba provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti |\n| 💰 **Sledování nákladů** | Kontrola rozpočtu a přehled o cenách pro jednotlivé modely |\n| 📈 **Analytické vizualizace** | Přehledy využití modelů/poskytovatelů a zobrazení trendů |\n| 🧪 **Rámec hodnocení** | Testování zlaté sady s konfigurovatelnými strategiemi shody |\n\n### ☁️ Nasazení a platforma\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| 🌐 **Nasazení kdekoli** | Localhost, VPS, Docker, cloudová prostředí |\n| 💾 **Synchronizace s cloudem** | Synchronizace konfigurace přes cloud worker |\n| 🔄 **Zálohování/Obnovení** | Toky exportu/importu a obnovy po havárii |\n| 🧙 **Průvodce nástupem** | Průvodce prvním spuštěním |\n| 🔧 **Panel nástrojů CLI** | Nastavení oblíbených kódovacích nástrojů jedním kliknutím |\n| 🎮 **Modelové hřiště** | Otestujte libovolného poskytovatele/model/koncový bod z řídicího panelu |\n| 🔏 **Přepínač otisků prstů v příkazovém řádku** | Porovnávání otisků prstů podle poskytovatele v Nastavení &gt; Zabezpečení |\n| 🌐 **i18n (30 jazyků)** | Plná jazyková podpora dashboardu a dokumentace s psaním zprava doleva |\n| 📂 **Adresář vlastních dat** | Přepsání `DATA_DIR` pro umístění úložiště |\n\n### Hluboký pohled na funkce\n\n#### Chytrá záložní funkce s praktickou kontrolou nákladů\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyž selže kvóta, rychlost nebo stav, OmniRoute automaticky přejde k dalšímu kandidátovi bez nutnosti ručního přepínání.\n\n#### Správa protokolů, která je viditelná a ovladatelná\n\n- MCP + A2A jsou viditelné v uživatelském rozhraní a dokumentaci (nejsou skryté)\n- API pro stav protokolu zpřístupňují živá provozní data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnují akce pro operace 2. dne (přepínání kombinací, resetování jističů, zrušení úkolů)\n\n#### Pracovní postup překladatele + validace\n\nOblast překladatele zahrnuje:\n\n- **Hřiště** : kontroly transformace požadavků\n- **Tester chatu** : kompletní okružní cesta požadavku/odpovědi\n- **Testovací stolice** : více případů v jednom běhu\n- **Živý monitor** : zobrazení provozu v reálném čase\n\nPlus validace protokolu se skutečnými klienty pomocí `npm run test:protocols:e2e` .\n\n> 📖 **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** — Referenční informace o nástrojích, konfigurace IDE a příklady klientů\n>\n> 📖 **[Soubor README pro A2A Server](src/lib/a2a/README.md)** — Dovednosti, metody JSON-RPC, streamování a životní cyklus úloh\n\n## 🧪 Hodnocení (Evals)\n\nOmniRoute obsahuje vestavěný hodnotící rámec pro testování kvality odpovědí LLM v porovnání se zlatou sadou. Přístup k němu je možný přes **Analýzy → Hodnocení** v dashboardu.\n\n### Vestavěná zlatá sada\n\nPředinstalovaná sada „OmniRoute Golden Set“ obsahuje testovací případy pro:\n\n- Zdravím, matematika, zeměpis, generování kódu\n- Shoda s formátem JSON, překlad, generování markdownů\n- Bezpečnostní odmítnutí (škodlivý obsah), počítání, booleovská logika\n\n### Strategie hodnocení\n\n| Strategie | Popis | Příklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Výstup se musí přesně shodovat | `\"4\"` |\n| `contains` | Výstup musí obsahovat podřetězec (bez rozlišení velkých a malých písmen) | `\"Paris\"` |\n| `regex` | Výstup musí odpovídat vzoru regulárních výrazů | `\"1.*2.*3\"` |\n| `custom` | Vlastní JS funkce vrací true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Průvodce nastavením\n\n### Nastavení protokolu (MCP + A2A)\n\n<details>\n<summary><b>🧩 Nastavení MCP (Model Context Protocol)</b></summary>\n</details>\n\nSpuštění MCP transportu v režimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporučený postup ověření:\n\n1. Připojte svého MCP klienta přes stdio.\n2. Spusťte `omniroute_get_health` .\n3. Spusťte `omniroute_list_combos` .\n4. Otevřete `/dashboard/mcp` pro ověření prezenčního signálu, aktivity a auditu.\n\nUžitečná API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n<details>\n<summary><b>🤝 Nastavení A2A (Agent2Agent)</b></summary>\n</details>\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat úkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSpráva životního cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvozní uživatelské rozhraní:\n\n- `/dashboard/a2a` pro pozorovatelnost úloh/stavů/streamů a akce kouření\n\n<details>\n<summary><b>🧪 Komplexní validace protokolu</b></summary>\n</details>\n\nOvěřte oba protokoly se skutečnými klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTím se ověřuje:\n\n- Připojení/seznam/volání klienta MCP SDK\n- A2A objevování/odesílání/streamování/získávání/zrušení\n- Křížová kontrola dat v auditu MCP a API pro správu úloh A2A\n\n<details>\n<summary><b>💳 Poskytovatelé předplatného</b></summary>\n</details>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionály:** Pro složité úkoly používejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvótu pro každý model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Správa limitů účtu Codex (5h + týdně)\n\nKaždý účet Codex má nyní přepínače zásad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinového prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zásadu týdenního prahu okna.\n- Prahové chování: když povolené okno dosáhne využití &gt;=90 %, je daný účet přeskočen.\n- Chování rotace: OmniRoute automaticky přesměruje na další způsobilý účet Codex.\n- Chování při resetování: Po `resetAt` určité doby se účet automaticky opět stane způsobilým.\n\nScénáře:\n\n- `5h ON` + `Weekly ON` : účet je přeskočen, když kterékoli z oken dosáhne prahové hodnoty.\n- `5h OFF` + `Weekly ON` : účet může být zablokován pouze týdenním používáním.\n- `5h ON` + `Weekly OFF` : účet může být zablokován pouze při 5hodinovém používání.\n- `resetAt` passed: účet se automaticky znovu zapne (bez ručního opětovného povolení).\n\n### Gemini CLI (ZDARMA 180 000/měsíc!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepší hodnota:** Obrovská bezplatná úroveň! Použijte ji před placenými úrovněmi.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n<details>\n<summary><b>🔑 Poskytovatelé klíčů API</b></summary>\n</details>\n\n### NVIDIA NIM (BEZPLATNÝ přístup pro vývojáře — více než 70 modelů)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Získejte zdarma klíč API (včetně 1000 inferenčních kreditů)\n3. Ovládací panel → Přidat poskytovatele → NVIDIA NIM:\n - Klíč API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a více než 50 dalších\n\n**Tip pro profesionály:** API kompatibilní s OpenAI – funguje bez problémů s překladem formátů OmniRoute!\n\n### Hluboké vyhledávání\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatná úroveň!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Získejte klíč API (včetně bezplatné úrovně)\n3. Ovládací panel → Přidat poskytovatele → Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionály:** Ultrarychlá inference – nejlepší pro kódování v reálném čase!\n\n### OpenRouter (100+ modelů)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → OpenRouter\n\n**Modely:** Získejte přístup k více než 100 modelům od všech hlavních poskytovatelů prostřednictvím jediného klíče API.\n\n<details>\n<summary><b>💰 Levní poskytovatelé (záložní)</b></summary>\n</details>\n\n### GLM-4.7 (Denní reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Získejte klíč API z kódovacího plánu\n3. Nástěnka → Přidat klíč API:\n - Poskytovatel: `glm`\n - Klíč API: `your-key`\n\n**Použití:** `glm/glm-4.7`\n\n**Tip pro profesionály:** Programovací plán nabízí 3× kvótu za cenu 1/7! Obnovuje se denně v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionály:** Nejlevnější varianta pro dlouhý kontext (1 milion tokenů)!\n\n### Kimi K2 (paušální poplatek 9 dolarů měsíčně)\n\n1. Odebírat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `kimi/kimi-latest`\n\n**Tip pro profesionály:** Fixních 9 $/měsíc za 10 milionů tokenů = efektivní náklady 0,90 $/1 milion!\n\n<details>\n<summary><b>🆓 BEZPLATNÍ poskytovatelé (nouzové zálohování)</b></summary>\n</details>\n\n### iFlow (5 BEZPLATNÝCH modelů přes OAuth)\n\n```bash\nDashboard → Connect iFlow\n→ iFlow OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kódem zařízení)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n<details>\n<summary><b>🎨 Vytvořte kombinace</b></summary>\n</details>\n\n### Příklad 1: Maximalizace předplatného → Levné zálohování\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Příklad 2: Pouze zdarma (nulové náklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n<details>\n<summary><b>🔧 Integrace s rozhraním příkazového řádku</b></summary>\n</details>\n\n### IDE kurzoru\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jedním kliknutím použijte stránku **Nástroje CLI** na řídicím panelu nebo ručně upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Možnost 1 – Dashboard (doporučeno):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Možnost 2 – Manuální úprava:** Úprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznámka:** OpenClaw funguje pouze s lokálním OmniRoute. Místo `localhost` použijte `127.0.0.1` , abyste se vyhnuli problémům s rozlišením IPv6.\n\n### Cline / Pokračovat / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Přidání OmniRoute jako vlastního poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvořte/upravte `opencode.json` v kořenovém adresáři projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` přidejte jakýkoli model dostupný ve vašem koncovém bodu OmniRoute `/v1/models` . Použijte formát `provider/model-id` z vašeho dashboardu OmniRoute.\n\n---\n\n## 🐛 Řešení problémů\n\n<details>\n<summary><b>Kliknutím rozbalíte průvodce řešením problémů</b></summary>\n</details>\n\n**\"Jazykový model neposkytoval zprávy\"**\n\n- Kvóta poskytovatele vyčerpána → Zkontrolujte sledování kvót na řídicím panelu\n- Řešení: Použijte záložní kombinovanou variantu nebo přejděte na levnější úroveň\n\n**Omezení rychlosti**\n\n- Kvóta předplatného vyčerpána → Přechod na GLM/MiniMax\n- Přidat kombo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vypršela**\n\n- Automaticky aktualizováno službou OmniRoute\n- Pokud problémy přetrvávají: Ovládací panel → Poskytovatel → Znovu připojit\n\n**Vysoké náklady**\n\n- Zkontrolujte statistiky využití v sekci Nástěnka → Náklady\n- Přepnout primární model na GLM/MiniMax\n- Pro nekritické úlohy použijte bezplatnou úroveň (Gemini CLI, iFlow).\n\n**Porty řídicího panelu/API jsou nesprávné**\n\n- `PORT` je kanonický základní port (a standardně port API)\n- `API_PORT` přepisuje pouze posluchač API kompatibilní s OpenAI.\n- `DASHBOARD_PORT` přepisuje pouze posluchač dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaši veřejnou URL adresu řídicího panelu (pro zpětná volání OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ověřte, zda `BASE_URL` odkazuje na vaši spuštěnou instanci.\n- Ověřte, zda `CLOUD_URL` odkazuje na váš očekávaný cloudový koncový bod.\n- Udržujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na straně serveru.\n\n**První přihlášení nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud není nastaveno, záložní heslo je `123456`\n\n**Žádné protokoly požadavků**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test připojení ukazuje „Neplatné“ pro poskytovatele kompatibilní s OpenAI**\n\n- Mnoho poskytovatelů nezpřístupňuje koncový bod `/models`\n- OmniRoute v1.0.6+ zahrnuje záložní ověření pomocí dokončení chatu\n- Zajistěte, aby základní URL adresa obsahovala příponu `/v1`\n\n### 🔐 OAuth na vzdáleném serveru\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Důležité pro uživatele, kteří provozují OmniRoute na VPS, Dockeru nebo jakémkoli vzdáleném serveru**\n\n#### Proč selhává OAuth v rozhraní CLI Antigravity / Gemini na vzdálených serverech?\n\nPoskytovatelé rozhraní CLI **Antigravity** a **Gemini** používají **Google OAuth 2.0** . Google vyžaduje, aby se `redirect_uri` v toku OAuth přesně shodoval s jedním z předregistrovaných URI v konzoli Google Cloud Console aplikace.\n\nPřihlašovací údaje OAuth, které jsou součástí OmniRoute, jsou registrovány **pouze pro `localhost`** . Když přistupujete k OmniRoute na vzdáleném serveru (např. `https://omniroute.myserver.com` ), Google odmítne ověření pomocí:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Řešení: Nakonfigurujte si vlastní přihlašovací údaje OAuth\n\nV Google Cloud Console je potřeba vytvořit **ID klienta OAuth 2.0** s URI vašeho serveru.\n\n#### Krok za krokem\n\n**1. Otevřete konzoli Google Cloud**\n\nPřejděte na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvořte nové ID klienta OAuth 2.0**\n\n- Klikněte na **„+ Vytvořit přihlašovací údaje“** → **„ID klienta OAuth“**\n- Typ aplikace: **„Webová aplikace“**\n- Název: cokoli chcete (např. `OmniRoute Remote` )\n\n**3. Přidejte autorizované URI pro přesměrování**\n\nDo pole **„Autorizované identifikátory URI pro přesměrování“** přidejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraďte `your-server.com` doménou nebo IP adresou vašeho serveru (v případě potřeby uveďte i port, např. `http://45.33.32.156:20128/callback` ).\n\n**4. Uložte a zkopírujte přihlašovací údaje**\n\nPo vytvoření Google zobrazí **ID klienta** a **tajný kód klienta** .\n\n**5. Nastavení proměnných prostředí**\n\nVe vašem souboru `.env` (nebo proměnných prostředí Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu připojit**\n\nŘídicí panel → Poskytovatelé → Antigravity (nebo Gemini CLI) → OAuth\n\nGoogle nyní bude správně přesměrovávat na `https://your-server.com/callback` .\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nPokud si teď nechcete nastavovat vlastní přihlašovací údaje, můžete stále použít **ruční postup pro URL** :\n\n1. OmniRoute otevírá autorizační URL od Googlu\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru).\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče (i když se stránka nenačte)\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute.\n5. Klikněte na **„Připojit“**\n\n> To funguje, protože autorizační kód v URL adrese je platný bez ohledu na to, zda se načetla přesměrovací stránka.\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nChcete-li získat přístup k přihlašovacím údajům bez vlastní konfigurace, můžete použít následující postup:\n\n1. OmniRoute otevře URL autorizace Google\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru)\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute\n5. Klikněte na **„Připojit\"**\n\n> Toto řešení funguje, protože autorizační kód v URL adrese je platný bez ohledu na načtení přesměrovací stránky.\n\n---\n\n## 🛠️ Technologický stack\n\n<details>\n<summary><b>Kliknutím rozbalíte podrobnosti o technologickém stacku</b></summary>\n</details>\n\n- **Runtime** : Node.js 18–22 LTS (⚠️ Node.js 24+ **není podporován** — nativní binární soubory `better-sqlite3` jsou nekompatibilní)\n- **Jazyk** : TypeScript 5.9 — **100% TypeScript** napříč `src/` a `open-sse/` ( `any` v základních modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databáze** : LowDB (JSON) + SQLite (stav domény + protokoly proxy + audit MCP + rozhodnutí o směrování)\n- **Schémata** : Zod (validace I/O nástrojů MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamování** : Události odeslané serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klíče + autorizace s rozsahem MCP\n- **Testování** : Node.js test runner + Vitest (900+ testů včetně unit, integračních, E2E)\n- **CI/CD** : Akce GitHubu (automatické publikování v npm + Docker Hub při vydání)\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **Balíček** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistič, exponenciální odstavení, ochrana proti hromům, falešné TLS, automatické kombinované samoopravování\n\n---\n\n## 📖 Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uživatelská příručka](docs/USER_GUIDE.md) | Poskytovatelé, kombinace, integrace CLI, nasazení |\n| [Referenční informace k API](docs/API_REFERENCE.md) | Všechny koncové body s příklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nástrojů MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamování, správa úloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorové bodování, balíčky režimů, samoléčba |\n| [Odstraňování problémů](docs/TROUBLESHOOTING.md) | Běžné problémy a jejich řešení |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a interní prvky systému |\n| [Přispívání](CONTRIBUTING.md) | Nastavení a pokyny pro vývoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpečnostní zásady](SECURITY.md) | Hlášení zranitelností a bezpečnostní postupy |\n| [Nasazení virtuálního počítače](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletní průvodce: Nastavení virtuálního počítače + nginx + Cloudflare |\n| [Galerie funkcí](docs/FEATURES.md) | Vizuální prohlídka řídicího panelu se snímky obrazovky |\n| [Kontrolní seznam vydání](docs/RELEASE_CHECKLIST.md) | Kroky ověření před vydáním |\n\n---\n\n## 🗺️ Plán\n\nOmniRoute má **v plánu více než 210 funkcí** v několika fázích vývoje. Zde jsou klíčové oblasti:\n\n| Kategorie | Plánované funkce | Hlavní body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| 🧠 **Směrování a inteligence** | 25+ | Směrování s nejnižší latencí, směrování založené na tagech, kontrola kvót před výstupem, výběr účtu P2C |\n| 🔒 **Zabezpečení a dodržování předpisů** | 20+ | Zpevnění SSRF, maskování přihlašovacích údajů, limit rychlosti pro každý koncový bod, stanovení rozsahu klíčů pro správu |\n| 📊 **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledování kvót v reálném čase, sledování nákladů podle modelu |\n| 🔄 **Integrace poskytovatelů** | 20+ | Dynamický registr modelů, doba zchlazení poskytovatelů, Codex pro více účtů, analýza kvót Copilota |\n| ⚡ **Výkon** | 15+ | Dvojitá vrstva mezipaměti, mezipaměť výzev, mezipaměť odpovědí, udržování streamování, dávkové API |\n| 🌐 **Ekosystém** | 10+ | WebSocket API, horké opětovné načítání konfigurace, distribuované úložiště konfigurace, komerční režim |\n\n### 🔜 Již brzy\n\n- 🔗 **Integrace OpenCode** — Nativní podpora poskytovatelů pro IDE kódování s AI v OpenCode\n- 🔗 **Integrace TRAE** — Plná podpora vývojového rámce TRAE pro umělou inteligenci\n- 📦 **Dávkové API** — Asynchronní dávkové zpracování hromadných požadavků\n- 🎯 **Směrování na základě tagů** — Směrování požadavků na základě vlastních tagů a metadat\n- 💰 **Strategie nejnižších nákladů** – Automaticky vybere nejlevnějšího dostupného poskytovatele\n\n> 📝 Úplné specifikace funkcí jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobných specifikací)\n\n---\n\n## 👥 Přispěvatelé\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Přispěvatelé](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak přispět\n\n1. Vytvoření forku repozitáře\n2. Vytvořte si vlastní větev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrďte změny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do větve ( `git push origin feature/amazing-feature` )\n5. Otevřít žádost o změny (pull request)\n\nPodrobné pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydání nové verze\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Hvězdná historie\n\n## Hvězdáři v průběhu času\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvězdáři v průběhu času](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## 🙏 Poděkování\n\nZvláštní poděkování patří **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** – původnímu projektu, který inspiroval tento fork. OmniRoute staví na tomto neuvěřitelném základu s dalšími funkcemi, multimodálními API a kompletním přepsáním TypeScriptu.\n\nZvláštní poděkování patří **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – původní implementaci Go, která inspirovala tento JavaScriptový port.\n\n---\n\n## 📄 Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n<div align=\"center\">\n <sub>Vytvořeno s ❤️ pro vývojáře, kteří programují 24 hodin denně, 7 dní v týdnu</sub>\n <br>\n <sub><p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\">omniroute.online</a></p></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "a12622b3d816fc9357293474e8366becae95cc25": {"t": 1785764467.8171098, "n": 91323, "h": "44323280802cfd73", "c": "# 🚀 OmniRoute — Bezplatná brána umělé inteligence\n\n### Nikdy nepřestávejte s kódováním. Chytré směrování k **BEZPLATNÝM a levným modelům AI** s automatickým přepínáním mezi záložními systémy.\n\n_Váš univerzální API proxy – jeden endpoint, více než 44 poskytovatelů, nulové výpadky. Nyní s orchestrací agentů **MCP a A2A** ._\n\n**Dokončení chatu • Vkládání • Generování obrázků • Video • Hudba • Audio • Změna pořadí • **Vyhledávání na webu** • MCP server • A2A protokol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n</div>\n<p data-md-type=\"paragraph\"><a href=\"https://www.npmjs.com/package/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/npm/v/omniroute?color=cb3837&amp;logo=npm\" alt=\"verze npm\" data-md-type=\"image\"><a href=\"https://hub.docker.com/r/diegosouzapw/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&amp;logo=docker&amp;color=2496ED\" alt=\"Docker Hub\" data-md-type=\"image\"><a href=\"https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/github/license/diegosouzapw/OmniRoute\" alt=\"Licence\" data-md-type=\"image\"><a href=\"https://omniroute.online\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&amp;logoColor=white\" alt=\"Webové stránky\" data-md-type=\"image\"><a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&amp;logoColor=white\" alt=\"WhatsApp\" data-md-type=\"image\"></p>\n<p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\" data-md-type=\"link\">🌐 Webové stránky</a> • <a href=\"#-quick-start\" data-md-type=\"link\">🚀 Rychlý start</a> • <a href=\"#-key-features\" data-md-type=\"link\">💡 Funkce</a> • <a href=\"#-documentation\" data-md-type=\"link\">📖 Dokumentace</a> • <a href=\"#-pricing-at-a-glance\" data-md-type=\"link\">💰 Ceník</a> • <a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\">💬 WhatsApp</a></p>\n<div data-md-type=\"block_html\"></div>\n\n🌐 **Dostupné v:** 🇺🇸 [Angličtina](README.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [maďarština](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonésie](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nizozemsko](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)\n\n---\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| --- | --- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n\n\n### 🆕 What's New in v3.0.0\n\n| Area | Change |\n| --- | --- |\n| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| 🐛 **omniModel Tag Leak** | Internal `<omniModel>` tags no longer leak to clients in SSE streams (#585) |\n| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| 🔧 **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n\n\n## 🖼️ Hlavní ovládací panel\n\n<div align=\"center\"> <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"Řídicí panel OmniRoute\" width=\"800\"> </div>\n\n---\n\n## 📸 Náhled řídicího panelu\n\n<details>\n<summary><b>Kliknutím zobrazíte snímky obrazovky z řídicího panelu</b></summary>\n</details>\n\n| Strana | Snímek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelé** | ![Poskytovatelé](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdraví** | ![Zdraví](docs/screenshots/04-health.png) |\n| **Překladatel** | ![Překladatel](docs/screenshots/05-translator.png) |\n| **Nastavení** | ![Nastavení](docs/screenshots/06-settings.png) |\n| **Nástroje CLI** | ![Nástroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly používání** | ![Používání](docs/screenshots/08-usage.png) |\n| **Koncové body** | ![Koncové body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### 🤖 Bezplatný poskytovatel umělé inteligence pro vaše oblíbené programátory\n\n_Připojte libovolný nástroj IDE nebo CLI s umělou inteligencí přes OmniRoute — bezplatnou API bránu pro neomezené kódování._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openclaw/openclaw\"><img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"><br><b>OpenClaw</b></a><br> <sub>⭐ 205 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/HKUDS/nanobot\"><img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"><br><b>NanoBot</b></a><br> <sub>⭐ 20,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/sipeed/picoclaw\"><img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"><br><b>PicoClaw</b></a><br> <sub>⭐ 14,6 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/zeroclaw-labs/zeroclaw\"><img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"><br><b>ZeroClaw</b></a><br> <sub>⭐ 9,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/nearai/ironclaw\"><img src=\"./public/providers/ironclaw.png\" alt=\"Železný dráp\" width=\"48\"><br><b>Železný dráp</b></a><br> <sub>⭐ 2,1 tisíce</sub> </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anomalyco/opencode\"><img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"><br><b>OpenCode</b></a><br> <sub>⭐ 106 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openai/codex\"><img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"><br><b>Codex CLI</b></a><br> <sub>⭐ 60,8 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anthropics/claude-code\"><img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"><br><b>Claude Code</b></a><br> <sub>⭐ 67,3 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/google-gemini/gemini-cli\"><img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"><br> <b>Gemini CLI</b></a><br> <sub>⭐ 94,7 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/Kilo-Org/kilocode\"><img src=\"./public/providers/kilocode.png\" alt=\"Kilo kód\" width=\"48\"><br><b>Kilo kód</b></a><br> <sub>⭐ 15,5 tisíc</sub> </td>\n </tr>\n </table>\n\n<sub>📡 Všichni agenti se připojují přes <code>http://localhost:20128/v1</code> nebo <code>http://cloud.omniroute.online/v1</code> — jedna konfigurace, neomezené modely a kvóty</sub>\n\n---\n\n## 🤔 Proč OmniRoute?\n\n**Přestaňte plýtvat penězi a narážet na limity:**\n\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Kvóta předplatného vyprší každý měsíc\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Limity rychlosti vám zabrání v kódování\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Drahá API (20–50 USD/měsíc na poskytovatele)\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Ruční přepínání mezi poskytovateli\n\n**OmniRoute to řeší:**\n\n- ✅ **Maximalizujte předplatné** – Sledujte kvótu, využijte každou částku před resetováním\n- ✅ **Automatické záložní** – Předplatné → API klíč → Levné → Zdarma, žádné výpadky\n- ✅ **Více účtů** – Round-robin mezi účty u jednotlivých poskytovatelů\n- ✅ **Univerzální** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakýmkoli nástrojem CLI\n\n---\n\n## 📧 Podpora\n\n> 💬 **Přidejte se k naší komunitě!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získejte pomoc, sdílejte tipy a buďte v obraze.\n\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problémy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitní skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Přispívání** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevřete žádost o příspěvek nebo si vyberte `good first issue`\n- **Původní projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### 🐛 Hlásíte chybu?\n\nPři otevírání problému spusťte příkaz system-info a přiložte vygenerovaný soubor:\n\n```bash\nnpm run system-info\n```\n\nTím se vygeneruje soubor `system-info.txt` s verzí Node.js, verzí OmniRoute, podrobnostmi o operačním systému, nainstalovanými nástroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systémovými balíčky – vše, co potřebujeme k rychlé reprodukci vašeho problému. Soubor přiložte přímo k vašemu problému na GitHubu.\n\n---\n\n## 🔄 Jak to funguje\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 Co řeší OmniRoute — 30 skutečných problémů a případů použití\n\n> **Každý vývojář používající nástroje umělé inteligence se s těmito problémy setkává denně.** OmniRoute byl vytvořen tak, aby je všechny vyřešil – od překročení nákladů po regionální bloky, od nefunkčních toků OAuth až po operace s protokoly a sledovatelnost v podniku.\n\n<details>\n<summary><b>💸 1. „Platím si drahé předplatné, ale stále mě ruší limity“</b></summary>\n</details>\n\nVývojáři platí za Claude Pro, Codex Pro nebo GitHub Copilot 20–200 dolarů měsíčně. I při platbě má kvóta strop – 5 hodin používání, týdenní limity nebo limity rychlosti za minutu. Uprostřed kódovací relace poskytovatel přestane reagovat a vývojář ztrácí plynulost a produktivitu.\n\n**Jak to OmniRoute řeší:**\n\n- **Inteligentní čtyřúrovňová záložní služba** – Pokud dojde kvóta předplatného, ​​automaticky se přesměruje na API klíč → Levné → Zdarma bez manuálního zásahu\n- **Sledování kvót v reálném čase** – Zobrazuje spotřebu tokenů v reálném čase s odpočítáváním resetování (5 hodin, denně, týdně)\n- **Podpora více účtů** – Více účtů u jednoho poskytovatele s automatickým přepínáním – když jeden dojde, přepne se na další\n- **Vlastní kombinace** — Přizpůsobitelné záložní řetězce se 6 strategiemi vyvažování (fill-first, round robin, P2C, náhodné, nejméně používané, nákladově optimalizované)\n- **Codex Business Quotas** — Sledování kvót pracovního prostoru firmy/týmu přímo v dashboardu\n\n<details>\n<summary><b>🔌 2. „Potřebuji použít více poskytovatelů, ale každý má jiné API“</b></summary>\n</details>\n\nOpenAI používá jeden formát, Claude (Anthropic) jiný a Gemini ještě třetí. Pokud chce vývojář testovat modely od různých poskytovatelů nebo mezi nimi přecházet, musí překonfigurovat SDK, změnit koncové body a vypořádat se s nekompatibilními formáty. Vlastní poskytovatelé (FriendLI, NIM) mají nestandardní koncové body modelů.\n\n**Jak to OmniRoute řeší:**\n\n- **Sjednocený koncový bod** — Jeden `http://localhost:20128/v1` slouží jako proxy pro všech 44+ poskytovatelů.\n- **Překlad formátu** — Automatický a transparentní: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Sanitizace odpovědí** — Odstraňuje nestandardní pole ( `x_groq` , `usage_breakdown` , `service_tier` ), která porušují OpenAI SDK v1.83+\n- **Normalizace rolí** — Převádí `developer` → `system` pro poskytovatele bez OpenAI; `system` → `user` pro GLM/ERNIE\n- **Extrakce tagů Think** — Extrahuje bloky `<think>` z modelů, jako je DeepSeek R1, do standardizovaného `reasoning_content`\n- **Strukturovaný výstup pro Gemini** — `json_schema` → automatická konverze `responseMimeType` / `responseSchema`\n- **Výchozí hodnota `stream` je `false`** – Odpovídá specifikaci OpenAI, čímž se zabrání neočekávanému SSE v Python/Rust/Go SDK.\n\n<details>\n<summary><b>🌐 3. „Můj poskytovatel AI blokuje můj region/zemi“</b></summary>\n</details>\n\nPoskytovatelé jako OpenAI/Codex blokují přístup z určitých geografických oblastí. Uživatelé se během připojení OAuth a API dostávají k chybám jako `unsupported_country_region_territory` . To je obzvláště frustrující pro vývojáře z rozvojových zemí.\n\n**Jak to OmniRoute řeší:**\n\n- **3úrovňová konfigurace proxy** – Konfigurovatelná proxy na 3 úrovních: globální (veškerý provoz), pro jednotlivé poskytovatele (pouze jeden poskytovatel) a pro jednotlivé připojení/klíč\n- **Barevně kódované odznaky proxy** – Vizuální indikátory: 🟢 globální proxy, 🟡 proxy poskytovatele, 🔵 proxy připojení, vždy zobrazující IP adresu\n- **Výměna tokenů OAuth prostřednictvím proxy** – tok OAuth také prochází přes proxy, čímž se řeší `unsupported_country_region_territory`\n- **Testy připojení přes proxy** – Testy připojení používají nakonfigurovaný proxy (již žádné přímé obcházení)\n- **Podpora SOCKS5** — Plná podpora proxy SOCKS5 pro odchozí směrování\n- **TLS Fingerprint Spoofing** — Otisk prstu TLS podobný prohlížeči pomocí `wreq-js` pro obcházení detekce botů\n- **🔏 Porovnávání otisků prstů v CLI** — Změní pořadí záhlaví a polí v těle serveru tak, aby odpovídala nativním binárním podpisům v CLI, čímž drasticky snižuje riziko nahlašování účtu. IP adresa proxy je zachována — získáte současně stealth **i** maskování IP adresy.\n\n<details>\n<summary><b>🆓 4. „Chci používat umělou inteligenci pro kódování, ale nemám peníze“</b></summary>\n</details>\n\nNe každý si může dovolit zaplatit 20–200 dolarů měsíčně za předplatné AI. Studenti, vývojáři z rozvíjejících se zemí, amatéři a freelanceři potřebují přístup ke kvalitním modelům za nulovou cenu.\n\n**Jak to OmniRoute řeší:**\n\n- **Vestavění poskytovatelé bezplatné úrovně** — Nativní podpora pro 100% bezplatné poskytovatele: iFlow (5 neomezených modelů přes OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezené modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisíc tokenů/měsíc zdarma)\n- **Ollama Cloud** — Cloudově hostované modely Ollama na `api.ollama.com` s bezplatnou úrovní „Light usage“; použijte prefix `ollamacloud/<model>`\n- **Kombinace pouze zdarma** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/měsíc s nulovými prostoji\n- **NVIDIA NIM Free Access** — ~40 RPM developerský přístup k více než 70 modelům na build.nvidia.com (přechod z kreditů na čisté limity rychlosti)\n- **Strategie optimalizace nákladů** – Strategie směrování, která automaticky vybere nejlevnějšího dostupného poskytovatele\n\n<details>\n<summary><b>🔒 5. „Potřebuji chránit svou bránu umělé inteligence před neoprávněným přístupem“</b></summary>\n</details>\n\nPři zpřístupnění brány umělé inteligence síti (LAN, VPS, Docker) může kdokoli s adresou spotřebovat tokeny/kvótu vývojáře. Bez ochrany jsou API zranitelná vůči zneužití, prompt injection a dalšímu zneužití.\n\n**Jak to OmniRoute řeší:**\n\n- **Správa klíčů API** – generování, rotace a vymezování rozsahu pro každého poskytovatele s vyhrazenou stránkou `/dashboard/api-manager`\n- **Oprávnění na úrovni modelu** – Omezení klíčů API na konkrétní modely ( `openai/*` , zástupné znaky) pomocí přepínače Povolit vše/Omezit\n- **Ochrana koncových bodů API** – Vyžaduje klíč pro `/v1/models` a blokuje konkrétní poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** — Všechny trasy dashboardu chráněné middlewarem `withAuth` + tokeny CSRF\n- **Omezovač rychlosti** — Omezování rychlosti na IP s konfigurovatelnými okny\n- **Filtrování IP adres** — Seznam povolených/blokovaných adres pro řízení přístupu\n- **Ochrana proti vkládání výzev** – Sanitizace proti škodlivým vzorcům výzev\n- **Šifrování AES-256-GCM** – přihlašovací údaje jsou v klidovém stavu šifrovány\n\n<details>\n<summary><b>🛑 6. „Můj poskytovatel selhal a já ztratil/a programovací tok“</b></summary>\n</details>\n\nPoskytovatelé umělé inteligence se mohou stát nestabilními, vracet chyby 5xx nebo dosáhnout dočasných limitů rychlosti. Pokud je vývojář závislý na jediném poskytovateli, je jeho práce přerušena. Bez jističů může opakované pokusy vést k pádu aplikace.\n\n**Jak to OmniRoute řeší:**\n\n- **Jistič pro každý model** – Automatické otevírání/zavírání s konfigurovatelnými prahovými hodnotami a dobou ochlazování (Zavřeno/Otevřeno/Poloviční otevření), rozsah definovaný pro každý model, aby se zabránilo kaskádování bloků\n- **Exponenciální odklad** — Progresivní zpoždění opakování\n- **Anti-Thundering Herd** — ochrana Mutex + semafor proti souběžným bouřím s opakovanými pokusy\n- **Kombinované záložní řetězce** – Pokud primární poskytovatel selže, automaticky se propadne řetězcem bez zásahu.\n- **Kombinovaný jistič** – Automaticky deaktivuje selhávajícího poskytovatele v rámci kombinovaného řetězce\n- **Dashboard stavu** — Monitorování provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti, latence p50/p95/p99\n\n<details>\n<summary><b>🔧 7. „Konfigurace každého nástroje umělé inteligence je zdlouhavá a opakující se“</b></summary>\n</details>\n\nVývojáři používají Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Každý nástroj potřebuje jinou konfiguraci (API endpoint, klíč, model). Překonfigurování při změně poskytovatele nebo modelu je ztráta času.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel nástrojů CLI** — Vyhrazená stránka s nastavením jedním kliknutím pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generátor konfigurace GitHub Copilot** – Generuje `chatLanguageModels.json` pro VS Code s hromadným výběrem modelu\n- **Průvodce zaváděním** – 4krokové nastavení pro začínající uživatele\n- **Jeden koncový bod, všechny modely** – jednou nakonfigurujte `http://localhost:20128/v1` a získejte přístup k více než 44 poskytovatelům\n\n<details>\n<summary><b>🔑 8. „Správa OAuth tokenů od více poskytovatelů je peklo“</b></summary>\n</details>\n\nClaude Code, Codex, Gemini CLI, Copilot – všechny používají OAuth 2.0 s tokeny s vypršením platnosti. Vývojáři se musí neustále znovu autentizovat, řešit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdálených serverech. Obzvláště problematický je OAuth v LAN/VPS.\n\n**Jak to OmniRoute řeší:**\n\n- **Automatická aktualizace tokenů** – Tokeny OAuth se obnovují na pozadí před vypršením platnosti.\n- **Vestavěný OAuth 2.0 (PKCE)** – Automatický tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** — Více účtů na poskytovatele prostřednictvím extrakce tokenů JWT/ID\n- **OAuth LAN/Remote Fix** — Detekce privátní IP adresy pro `redirect_uri` + manuální režim URL pro vzdálené servery\n- **OAuth Behind Nginx** — Používá `window.location.origin` pro kompatibilitu s reverzní proxy\n- **Průvodce vzdáleným OAuth** – Podrobný návod k přihlašovacím údajům Google Cloud na VPS/Dockeru\n\n<details>\n<summary><b>📊 9. „Nevím, kolik utrácím ani kde“</b></summary>\n</details>\n\nVývojáři používají více placených poskytovatelů, ale nemají jednotný přehled o výdajích. Každý poskytovatel má svůj vlastní fakturační panel, ale neexistuje žádný konsolidovaný přehled. Mohou se hromadit neočekávané náklady.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard pro analýzu nákladů** – Sledování nákladů na token a správa rozpočtu pro každého poskytovatele\n- **Rozpočtové limity na úroveň** – Strop výdajů na úroveň, který spouští automatický záložní režim\n- **Konfigurace cen podle modelu** – Konfigurovatelné ceny podle modelu\n- **Statistiky použití pro každý klíč API** — Počet požadavků a časové razítko posledního použití pro každý klíč\n- **Analytický panel** – Statistické karty, graf využití modelu, tabulka poskytovatelů s mírou úspěšnosti a latencí\n\n<details>\n<summary><b>🐛 10. „Nedokážu diagnostikovat chyby a problémy ve volání umělé inteligence.“</b></summary>\n</details>\n\nKdyž volání selže, vývojář neví, zda se jednalo o limit rychlosti, vypršelý token, špatný formát nebo chybu poskytovatele. Fragmentované protokoly napříč různými terminály. Bez sledovatelnosti je ladění metodou pokus-omyl.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel jednotných protokolů** – 4 karty: Protokoly požadavků, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlížeč protokolů konzole** — Prohlížeč protokolů v reálném čase ve stylu terminálu s barevně kódovanými úrovněmi, automatickým posouváním, vyhledáváním a filtrováním\n- **Protokoly proxy SQLite** – trvalé protokoly, které přežijí restart serveru\n- **Překladačské hřiště** — 4 režimy ladění: Hřiště (překlad formátu), Tester chatu (okružní), Testovací stůl (dávkový), Živý monitor (v reálném čase)\n- **Telemetrie požadavků** — latence p50/p95/p99 + trasování X-Request-Id\n- **Souborové protokolování s rotací** – Konzolový interceptor zachycuje vše do protokolu JSON s rotací na základě velikosti\n- **Zpráva o systémových informacích** — příkaz `npm run system-info` vygeneruje `system-info.txt` s kompletním popisem vašeho prostředí (verze uzlu, verze OmniRoute, operační systém, nástroje CLI, stav Dockeru/PM2). Přiložte jej při hlášení problémů pro okamžité třídění.\n\n<details>\n<summary><b>🏗️ 11. „Nasazení a údržba brány je složitá“</b></summary>\n</details>\n\nInstalace, konfigurace a údržba AI proxy v různých prostředích (lokální, VPS, Docker, cloud) je pracná. Problémy, jako jsou pevně zakódované cesty, `EACCES` u adresářů, konflikty portů a multiplatformní sestavení, přispívají k obtížím.\n\n**Jak to OmniRoute řeší:**\n\n- **npm globální instalace** — `npm install -g omniroute && omniroute` — hotovo\n- **Docker Multi-Platform** — AMD64 + nativní ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** — `base` (bez nástrojů CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopová aplikace Electron** — Nativní aplikace pro Windows/macOS/Linux se systémovou lištou, automatickým spuštěním a offline režimem\n- **Režim rozdělených portů** – API a řídicí panel na samostatných portech pro pokročilé scénáře (reverzní proxy, síťování kontejnerů)\n- **Cloud Sync** – Konfigurace synchronizace mezi zařízeními pomocí Cloudflare Workers\n- **Zálohy databází** — Automatické zálohování, obnovení, export a import všech nastavení\n\n<details>\n<summary><b>🌍 12. „Rozhraní je pouze v angličtině a můj tým nemluví anglicky“</b></summary>\n</details>\n\nTýmy v neanglicky mluvících zemích, zejména v Latinské Americe, Asii a Evropě, se potýkají s rozhraními pouze v angličtině. Jazykové bariéry snižují míru přijetí a zvyšují chyby v konfiguraci.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard i18n — 30 jazyků** — Všech 500+ kláves je přeloženo včetně arabštiny, bulharštiny, dánštiny, němčiny, španělštiny, finštiny, francouzštiny, hebrejštiny, hindštiny, maďarštiny, indonéštiny, italštiny, japonštiny, korejštiny, malajštiny, holandštiny, norštiny, polštiny, portugalštiny (PT/BR), rumunštiny, ruštiny, slovenštiny, švédštiny, thajštiny, ukrajinštiny, vietnamštiny, čínštiny, filipínštiny a angličtiny\n- **Podpora RTL** – Podpora psaní zprava doleva pro arabštinu a hebrejštinu\n- **Vícejazyčné soubory README** — 30 kompletních překladů dokumentace\n- **Výběr jazyka** — Ikona glóbu v záhlaví pro přepínání v reálném čase\n\n<details>\n<summary><b>🔄 13. „Potřebuji víc než jen chat – potřebuji vložené soubory, obrázky, zvuk.“</b></summary>\n</details>\n\nUmělá inteligence není jen dokončování chatu. Vývojáři potřebují generovat obrázky, přepisovat zvuk, vytvářet embeddedy pro RAG, měnit pořadí dokumentů a moderovat obsah. Každé API má jiný koncový bod a formát.\n\n**Jak to OmniRoute řeší:**\n\n- **Vkládání** — `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generování obrázků** — `/v1/images/generations` s 10 poskytovateli a více než 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Převod textu na video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Převod textu na hudbu** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Přepis zvuku** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Převod textu na řeč** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a další stávající poskytovatelé\n- **Moderování** — `/v1/moderations` — Kontroly bezpečnosti obsahu\n- **Změna pořadí** — `/v1/rerank` — Změna pořadí relevance dokumentu\n- **Responses API** — Plná podpora `/v1/responses` pro Codex\n\n<details>\n<summary><b>🧪 14. „Nemám způsob, jak testovat a porovnávat kvalitu napříč modely.“</b></summary>\n</details>\n\nVývojáři chtějí vědět, který model je pro jejich případ použití nejlepší – kód, překlad, uvažování – ale ruční porovnávání je pomalé. Neexistují žádné integrované nástroje pro vyhodnocování.\n\n**Jak to OmniRoute řeší:**\n\n- **Hodnocení LLM** — Testování Golden setu s 10 předinstalovanými případy zahrnujícími pozdravy, matematiku, geografii, generování kódu, dodržování JSON, překlad, markdown, odmítnutí bezpečnostních požadavků\n- **4 strategie shody** — `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovací lavice pro překladatelské hřiště** — Dávkové testování s více vstupy a očekávanými výstupy, porovnání napříč poskytovateli\n- **Tester chatu** — Kompletní okružní cesta s vizuálním vykreslováním odpovědí\n- **Živý monitor** — Stream všech požadavků procházejících proxy serverem v reálném čase\n\n<details>\n<summary><b>📈 15. „Potřebuji škálovat bez ztráty výkonu“</b></summary>\n</details>\n\nS rostoucím objemem požadavků generují stejné otázky bez ukládání do mezipaměti duplicitní náklady. Bez idempotence duplicitní požadavky plýtvají zpracováním. Je nutné dodržovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute řeší:**\n\n- **Sémantická mezipaměť** — Dvouvrstvá mezipaměť (signatura + sémantika) snižuje náklady a latenci\n- **Idempotence požadavku** — 5s deduplikační okno pro identické požadavky\n- **Detekce limitu rychlosti** – sledování otáček za minutu (RPM), minimální mezera a maximální souběžné sledování pro každého poskytovatele\n- **Upravitelné limity rychlosti** — Konfigurovatelné výchozí hodnoty v Nastavení → Odolnost s perzistencí\n- **Mezipaměť pro ověření klíčů API** — třívrstvá mezipaměť pro výkon produkčního prostředí\n- **Dashboard s telemetrií** – latence p50/p95/p99, statistiky mezipaměti, dostupnost\n\n<details>\n<summary><b>🤖 16. „Chci mít chování modelů globálně pod kontrolou“</b></summary>\n</details>\n\nVývojáři, kteří chtějí všechny odpovědi v určitém jazyce, se specifickým tónem nebo chtějí omezit tokeny pro uvažování. Konfigurace této funkce v každém nástroji/požadavku je nepraktická.\n\n**Jak to OmniRoute řeší:**\n\n- **Vložení systémového prompt** – Globální prompt aplikovaný na všechny požadavky\n- **Validace rozpočtu Thinking** — Řízení alokace tokenů na požadavek (průchozí, automatické, vlastní, adaptivní)\n- **6 strategií směrování** – Globální strategie, které určují, jak jsou požadavky distribuovány\n- **Směrovač se zástupnými znaky** — vzory `provider/*` dynamicky směrují k libovolnému poskytovateli\n- **Přepínání povolení/zakázání kombinací** – Přepínání kombinací přímo z řídicího panelu\n- **Přepínání poskytovatele** – Povolení/zakázání všech připojení pro poskytovatele jedním kliknutím\n- **Blokovaní poskytovatelé** – Vyloučení konkrétních poskytovatelů ze seznamu `/v1/models`\n\n<details>\n<summary><b>🧰 17. „Potřebuji nástroje MCP jako prvotřídní produktové funkce.“</b></summary>\n</details>\n\nMnoho bran umělé inteligence odhaluje MCP pouze jako skrytý implementační detail. Týmy potřebují viditelnou a spravovatelnou operační vrstvu.\n\n**Jak to OmniRoute řeší:**\n\n- MCP se zobrazuje v navigaci na řídicím panelu a na kartě protokolu koncového bodu.\n- Vyhrazená stránka pro správu MCP s procesy, nástroji, rozsahy a auditem\n- Vestavěný rychlý start pro `omniroute --mcp` a onboarding klienta\n\n<details>\n<summary><b>🧠 18. „Potřebuji orchestraci A2A se synchronizací a cestami úloh streamu.“</b></summary>\n</details>\n\nPracovní postupy agentů vyžadují jak přímé odpovědi, tak dlouhodobé streamované provádění s kontrolou životního cyklu.\n\n**Jak to OmniRoute řeší:**\n\n- Koncový bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamování SSE s šířením stavu terminálu\n- Rozhraní API životního cyklu úloh pro `tasks/get` a `tasks/cancel`\n\n<details>\n<summary><b>🛰️ 19. „Potřebuji skutečný stav procesu MCP, ne odhadovaný stav.“</b></summary>\n</details>\n\nProvozní týmy potřebují vědět, zda je MCP skutečně aktivní, nejen zda je API dosažitelné.\n\n**Jak to OmniRoute řeší:**\n\n- Soubor běhového heartbeatu s PID, časovými razítky, transportem, počtem nástrojů a režimem rozsahu\n- API stavu MCP kombinující prezenční signál a nedávnou aktivitu\n- Karty stavu uživatelského rozhraní pro zobrazení aktuálnosti procesů/provozuschopnosti/prezenčního signálu\n\n<details>\n<summary><b>📋 20. „Potřebuji auditovatelné provedení nástroje MCP“</b></summary>\n</details>\n\nKdyž nástroje mění konfiguraci nebo spouštějí operační akce, týmy potřebují forenzní sledovatelnost.\n\n**Jak to OmniRoute řeší:**\n\n- Protokolování auditu pro volání nástrojů MCP s podporou SQLite\n- Filtruje podle nástroje, úspěchu/neúspěchu, klíče API a stránkování\n- Tabulka auditu dashboardu + koncové body statistik pro automatizaci\n\n<details>\n<summary><b>🔐 21. „Potřebuji omezená oprávnění MCP pro každou integraci.“</b></summary>\n</details>\n\nRůzní klienti by měli mít přístup ke kategoriím nástrojů s nejnižšími oprávněními.\n\n**Jak to OmniRoute řeší:**\n\n- 9 detailních MCP sond pro kontrolovaný přístup k nástrojům\n- Vynucení rozsahu a viditelnost v uživatelském rozhraní správy MCP\n- Bezpečná výchozí poloha pro provozní nástroje\n\n<details>\n<summary><b>⚙️ 22. „Potřebuji provozní kontroly bez nutnosti přesouvání“</b></summary>\n</details>\n\nTýmy potřebují rychlé změny v běhovém prostředí během incidentů nebo nákladových událostí.\n\n**Jak to OmniRoute řeší:**\n\n- Přepněte aktivaci komba přímo z řídicího panelu MCP\n- Používejte profily odolnosti z předdefinovaných balíčků zásad\n- Resetujte stav jističe ze stejného ovládacího panelu\n\n<details>\n<summary><b>🔄 23. „Potřebuji živý přehled o životním cyklu úkolů A2A a jejich zrušení.“</b></summary>\n</details>\n\nBez přehledu o životním cyklu je obtížné třídit incidenty úkolů.\n\n**Jak to OmniRoute řeší:**\n\n- Výpis/filtrování úkolů podle státu/dovednosti s stránkováním\n- Podrobný přehled metadat úloh, událostí a artefaktů\n- Koncový bod zrušení úlohy a akce uživatelského rozhraní s potvrzením\n\n<details>\n<summary><b>🌊 24. „Potřebuji metriky aktivního streamu pro A2A zátěž“</b></summary>\n</details>\n\nStreamovací pracovní postupy vyžadují provozní přehled o souběžnosti a živých připojeních.\n\n**Jak to OmniRoute řeší:**\n\n- Čítače aktivních streamů integrované do stavu A2A\n- Časové razítko posledního úkolu a počty pro jednotlivé stavy\n- Karty A2A dashboardu pro monitorování provozu v reálném čase\n\n<details>\n<summary><b>🪪 25. „Potřebuji standardní vyhledávání agentů pro klienty“</b></summary>\n</details>\n\nExterní klienti a orchestratoři potřebují pro onboarding strojově čitelná metadata.\n\n**Jak to OmniRoute řeší:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazené v uživatelském rozhraní pro správu\n- API pro stav A2A zahrnuje metadata pro zjišťování pro automatizaci\n\n<details>\n<summary><b>🧭 26. „Potřebuji v uživatelském rozhraní produktu zjistitelnost protokolu.“</b></summary>\n</details>\n\nPokud uživatelé nemohou objevit protokolové povrchy, kvalita přijetí a podpory klesá.\n\n**Jak to OmniRoute řeší:**\n\n- Stránka Konsolidované **koncové body** s kartami pro koncové body Proxy, MCP, A2A a API\n- Přepínání stavu inline služby (Online/Offline) pro MCP a A2A\n- Odkazy z přehledu na vyhrazené karty pro správu\n\n<details>\n<summary><b>🧪 27. „Potřebuji komplexní ověření protokolu se skutečnými klienty.“</b></summary>\n</details>\n\nSimulované testy nestačí k ověření kompatibility protokolu před vydáním.\n\n**Jak to OmniRoute řeší:**\n\n- Sada E2E, která spouští aplikaci a používá skutečný transport klienta MCP SDK.\n- Klientské testy A2A pro toky zjišťování, odesílání, streamování, načítání a zrušení\n- Křížová kontrola tvrzení oproti API pro audit MCP a úkoly A2A\n\n<details>\n<summary><b>📡 28. „Potřebuji jednotnou pozorovatelnost napříč všemi rozhraními“</b></summary>\n</details>\n\nRozdělení pozorovatelnosti podle protokolu vytváří slepá místa a delší MTTR.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocené dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie požadavků napříč vrstvami OpenAI, MCP a A2A\n- Provozní API pro stav a automatizaci\n\n<details>\n<summary><b>💼 29. „Potřebuji jeden runtime pro proxy + nástroje + orchestraci agentů“</b></summary>\n</details>\n\nSpouštění mnoha samostatných služeb zvyšuje provozní náklady a počet poruch.\n\n**Jak to OmniRoute řeší:**\n\n- Proxy, MCP server a A2A server kompatibilní s OpenAI v jednom balíčku\n- Sdílené ověřování, odolnost, úložiště dat a pozorovatelnost\n- Konzistentní model politik napříč všemi interakčními plochami\n\n<details>\n<summary><b>🚀 30. „Potřebuji agentské pracovní postupy bez slepení kódu.“</b></summary>\n</details>\n\nTýmy ztrácejí rychlost při spojování více ad-hoc služeb a skriptů.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocená strategie koncových bodů pro klienty a agenty\n- Vestavěná uživatelská rozhraní pro správu protokolů a cesty pro ověřování kouře\n- Základy připravené pro produkční prostředí (zabezpečení, protokolování, odolnost, zálohování)\n\n### Příklady herních plánů (integrované případy užití)\n\n**Příručka A: Maximalizace placeného předplatného + levné zálohování**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Příručka B: Kódovací stack s nulovými náklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Příručka C: Nonstop záložní řetězec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Příručka D: Operace agentů s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Začněte zdarma — Nulové náklady na konfiguraci\n\n> Nastavte si kódování s umělou inteligencí během několika minut za **0 $/měsíc** . Propojte tyto bezplatné účty a využijte vestavěnou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelé odemčeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Připojení **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 – **neomezeně** |\n| 2 | Připojení k **iFlow** (Google OAuth) | kimi-k2-myšlení, qwen3-coder-plus, deepseek-r1... — **neomezeně** |\n| 3 | Připojení **Qwen** (kód zařízení) | qwen3-coder-plus, qwen3-coder-flash... — **neomezeně** |\n| 4 | Připojení **rozhraní příkazového řádku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180 000 GBP/měsíc zdarma** |\n| 5 | `/dashboard/combos` → Šablona **Free Stack (0 $)** | Automatické zařazení všech bezplatných poskytovatelů do routingu |\n\n**V libovolném IDE/CLI naveďte:** `http://localhost:20128/v1` · Klíč API: `any-string` · Hotovo.\n\n> **Volitelné doplňkové krytí (také zdarma):** Groq API klíč (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelů), Cerebras (1 milion tok/den).\n\n## ⚡ Rychlý start\n\n### 1) Nainstalujte a spusťte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uživatelé pnpm:** Po instalaci spusťte `pnpm approve-builds -g` , abyste povolili nativní skripty pro sestavení vyžadované programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard se otevírá na `http://localhost:20128` a základní URL API je `http://localhost:20128/v1` .\n\n| Příkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuštění serveru ( `PORT=20128` , API a dashboard na stejném portu) |\n| `omniroute --port 3000` | Nastavte kanonický/API port na 3000 |\n| `omniroute --mcp` | Spuštění MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevírat prohlížeč automaticky |\n| `omniroute --help` | Zobrazit nápovědu |\n\nVolitelný režim s rozděleným portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Připojte poskytovatele a vytvořte si klíč API\n\n1. Otevřete Dashboard → `Providers` a připojte alespoň jednoho poskytovatele (klíč OAuth nebo API).\n2. Otevřete Dashboard → `Endpoints` a vytvořte API klíč.\n3. (Volitelné) Otevřete Dashboard → `Combos` a nastavte záložní řetězec.\n\n### 3) Nasměrujte svůj kódovací nástroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilními s OpenAI.\n\n### 4) Povolení a ověření protokolů (v2.0)\n\n**MCP (pro operace řízené nástroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak připojte svého MCP klienta přes `stdio` a otestujte nástroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovní postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ověřte vše od začátku do konce (doporučeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ověřuje skutečné toky klientů MCP a A2A v porovnání se spuštěnou aplikací.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## 🐳 Docker\n\nOmniRoute je k dispozici jako veřejný obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlý běh:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostředí:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Používání Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | Štítek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovější stabilní verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuální verze |\n\n---\n\n## 🖥️ Desktopová aplikace – offline a vždy zapnutá\n\n> 🆕 **NOVINKA!** OmniRoute je nyní k dispozici jako **nativní desktopová aplikace** pro Windows, macOS a Linux.\n\nSpusťte OmniRoute jako samostatnou desktopovou aplikaci – pro lokální modely není potřeba žádný terminál, prohlížeč ani internet. Aplikace založená na platformě Electron obsahuje:\n\n- 🖥️ **Nativní okno** — Vyhrazené okno aplikace s integrací do systémové lišty\n- 🔄 **Automatické spuštění** — Spuštění OmniRoute po přihlášení do systému\n- 🔔 **Nativní oznámení** – Získejte upozornění na vyčerpání kvóty nebo problémy s poskytovateli\n- ⚡ **Instalace jedním kliknutím** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline režim** — Funguje plně offline s přiloženým serverem\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systémový zásobník\n\nPo minimalizaci se OmniRoute nachází v systémové liště a nabízí rychlé akce:\n\n- Otevřít řídicí panel\n- Změnit port serveru\n- Ukončit aplikaci\n\n📖 Úplná dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Přehled cen\n\n| Úroveň | Poskytovatel | Náklady | Obnovení kvóty | Nejlepší pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **💳 PŘEDPLATNÉ** | Claude Code (profesionál) | 20 dolarů měsíčně | 5 hodin + týdně | Již přihlášen/a k odběru |\n| Kodex (Plus/Pro) | 20–200 USD/měsíc | 5 hodin + týdně | Uživatelé OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisíc měsíčně + 1 tisíc denně | Každý! |\n| GitHub Copilot | 10–19 USD/měsíc | Měsíční | Uživatelé GitHubu |\n| **🔑 KLÍČ API** | NVIDIA NIM | **ZDARMA** (vývoj navždy) | ~40 ot./min | 70+ otevřených modelů |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší na světě |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisíc otáček za minutu | Ultrarychlá lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | Žádný | Nejlepší zdůvodnění ceny a kvality |\n| xAI Grok-4 Rychlý | **0,20/0,50 USD za 1 milion** 🆕 | Žádný | Nejrychlejší + volání nástroje, ultranízké |\n| xAI Grok-4 (standardní) | 0,20/1,50 USD za 1 milion 🆕 | Žádný | Vlajková loď Reasoning od xAI |\n| Mistral | Zkušební verze zdarma + placené | Omezená sazba | Evropská umělá inteligence |\n| OpenRouter | Platba za použití | Žádný | Více než 100 modelů agregováno. |\n| **💰 LEVNÉ** | GLM-5 (přes Z.AI) 🆕 | 0,5 USD/1 milion | Denně v 10:00 | Výstup 128 tisíc obrazových bodů, nejnovější vlajková loď |\n| GLM-4.7 | 0,6 USD/1 milion | Denně v 10:00 | Záloha rozpočtu |\n| MiniMax M2.5 🆕 | Vstup 0,3 USD/1 milion | 5hodinové válcování | Úvaha + agentní úkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinové válcování | Nejlevnější varianta |\n| Kimi K2.5 (Moonshot API) 🆕 | Platba za použití | Žádný | Přímý přístup k Moonshot API |\n| Kimi K2 | 9 dolarů měsíčně bez závazků | 10 milionů tokenů/měsíc | Předvídatelné náklady |\n| **🆓 ZDARMA** | iFlow | **0 dolarů** | Neomezený | 5 modelů neomezeně |\n| Qwen | **0 dolarů** | Neomezený | 4 modely neomezeně |\n| Kiro | **0 dolarů** | Neomezený | Claude Sonnet/Haiku (tvorce AWS) |\n\n> 🆕 **Přidány nové modely (březen 2026):** řada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkováno na 1143 ms – o 30 % rychlejší než Gemini 2.5 Flash), GLM-5 přes Z.AI s výstupem 128K, uvažování MiniMax M2.5, aktualizované ceny DeepSeek V3.2, Kimi K2.5 přes Moonshot Direct API.\n\n**💡 Kombinovaný balík za 0 $ — Kompletní bezplatná instalace:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\niFlow (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Nulové náklady. Nikdy nepřestávejte s kódováním.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a všechny záložní režimy se provede automaticky – žádné ruční přepínání.\n\n---\n\n---\n\n## 🆓 Bezplatné modely – Co skutečně získáte\n\n> Všechny níže uvedené modely jsou **100% zdarma a nevyžadují žádnou kreditní kartu** . OmniRoute mezi nimi automaticky propojí trasy, když dojde jedna kvóta – zkombinujte je všechny a získejte tak nerozlučnou kombinaci za 0 dolarů.\n\n### 🔵 CLAUDE MODELS (přes Kiro — AWS Builder ID)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-opus-4.6` | `kr/` | **Neomezený** | Nejnovější opus od Kira |\n\n### 🟢 MODELY IFLOW (Bezplatné OAuth — bez nutnosti platit kreditní kartou)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-plus` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `deepseek-r1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `minimax-m2.1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `kimi-k2` | `if/` | **Neomezený** | Žádný hlášený strop |\n\n### 🟡 MODELY QWEN (Ověření kódu zařízení)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-next` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `vision-model` | `qw/` | **Neomezený** | Multimodální (obrázky) |\n\n### 🟣 Rozhraní GEMINI CLI (Google OAuth)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisíc tok/měsíc** + 1 tisíc/den | Měsíční reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisíc měsíčně (sdílený bazén) | Vysoká kvalita |\n\n### ⚫ NVIDIA NIM (Bezplatný klíč API — build.nvidia.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vývojář) | Žádný limit tokenů | **~40 ot./min** | Více než 70 modelů; přechod na čisté limity sazeb v polovině roku 2025 |\n\nOblíbené bezplatné modely: `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`\n\n### ⚪ CEREBRAS (Bezplatný klíč API — inference.cerebras.ai)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenů/den** | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší inference LLM na světě; denně se resetuje |\n\nDostupné zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Bezplatný API klíč — console.groq.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisíc otáček za minutu** | 30 ot./min na model | Žádná kreditní karta; limit 429, neúčtováno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **💡 Ultimátní bezplatný zásobník:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> → iFlow (5 models, unlimited)\n> → Qwen (4 models, unlimited)\n> → Gemini CLI (180K/mo)\n> → Cerebras (1M tok/day)\n> → Groq (14.4K req/day)\n> → NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a už nikdy nebudete platit za umělou inteligenci.\n\n## 🎙️ Kombinovaná transkripce zdarma\n\n> Přepisujte libovolné audio/video za **0 $** – Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako záložní nástroj, Groq Whisper jako neomezená nouzová záloha.\n\n| Poskytovatel | Bezplatné kredity | Nejlepší model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| 🟢 **Deepgram** | **200 dolarů zdarma** (registrace) | `nova-3` — nejvyšší přesnost, více než 30 jazyků | Žádný limit RPM pro kredity zdarma |\n| 🔵 **AssemblyAI** | **50 dolarů zdarma** (registrace) | `universal-3-pro` — kapitoly, sentiment, osobní údaje | Žádný limit RPM pro kredity zdarma |\n| 🔴 **Groq** | **Navždy zdarma** | `whisper-large-v3` — OpenAI Šepot | 30 ot./min (omezená rychlost) |\n\n**Navrhovaná kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nPak v `/dashboard/media` → záložka **Přepis** : nahrajte libovolný zvukový nebo video soubor → vyberte kombinovaný koncový bod → získejte přepis v podporovaných formátech.\n\n## 💡 Klíčové vlastnosti\n\nOmniRoute v2.0 je navržen jako operační platforma, nikoli pouze jako proxy pro relé.\n\n### 🤖 Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dělá |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **MCP Server (16 nástrojů)** | Nástroje IDE/agent prostřednictvím 3 transportů: stdio, SSE ( `/api/mcp/sse` ), Streamovatelný HTTP ( `/api/mcp/stream` ) |\n| 🤝 **A2A server (JSON-RPC + SSE)** | Spouštění úloh mezi agenty se synchronizací a streamováním |\n| 🧭 **Konsolidovaná stránka koncových bodů** | Stránka pro správu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| 🎚️ **Přepínače pro povolení/zakázání služby** | Přepínače ZAP/VYP pro MCP a A2A s trvalým nastavením (výchozí: VYP) |\n| 🛰️ **Srdeční tep za běhu MCP** | Skutečný stav procesu (pid, doba provozuschopnosti, stáří heartbeatu, transport, režim rozsahu) |\n| 📋 **Auditní záznam MCP** | Filtrovatelné protokoly auditu s hodnocením úspěchu/neúspěchu a klíčovým přiřazením |\n| 🔐 **Vynucování rozsahu MCP** | 9 podrobných oprávnění pro řízený přístup k nástrojům |\n| 📡 **Správa životního cyklu úkolů A2A** | Seznam/filtrování úloh, kontrola událostí/artefaktů, zrušení spuštěných úloh |\n| 📋 **Objevení karty agenta** | `/.well-known/agent.json` pro automatické vyhledávání klientů |\n| 🧪 **Testovací postroj Protocol E2E** | Skutečné MCP SDK + toky klientů A2A v `test:protocols:e2e` |\n| ⚙️ **Provozní kontroly** | Kombinace přepínačů, použití profilů odolnosti, resetování jističů z jednoho ovládacího panelu |\n\n### 🧠 Směrování a inteligence\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| 🎯 **Inteligentní čtyřúrovňový záložní systém** | Automatická trasa: Předplatné → API klíč → Levné → Zdarma |\n| 📊 **Sledování kvót v reálném čase** | Počet tokenů v reálném čase + odpočet resetování pro každého poskytovatele |\n| 🔄 **Překlad formátu** | OpenAI ↔ Claude ↔ Gemini ↔ Odpovědi s konverzemi bezpečnými pro schéma |\n| 👥 **Podpora více účtů** | Více účtů na poskytovatele s inteligentním výběrem |\n| 🔄 **Automatická aktualizace tokenů** | Tokeny OAuth se automaticky obnovují při opakovaném pokusu. |\n| 🎨 **Vlastní kombinace** | 6 vyvažovacích strategií + řízení záložního řetězce |\n| 🌐 **Směrovač se zástupnými znaky** | dynamické směrování `provider/*` |\n| 🧠 **Přemýšlení o rozpočtových kontrolách** | Limity pro průchozí, automatické, vlastní a adaptivní uvažování |\n| 🔀 **Aliasy modelů** | Vestavěné + vlastní aliasování modelů a bezpečnost migrace |\n| ⚡ **Degradace pozadí** | Směrujte úlohy na pozadí s nízkou prioritou na levnější modely |\n| 🧪 **Chytré směrování s ohledem na úkoly** | Automatický výběr modelu podle typu obsahu (kódování/vize/analýza/sumarizace) |\n| 💬 **Vstřikování do systému** | Globální kontroly chování uplatňované konzistentně |\n| 📄 **Kompatibilita API pro odpovědi** | Plná podpora `/v1/responses` pro Codex a pokročilé agentické pracovní postupy |\n\n### 🎵 Multimodální API\n\n| Funkce | Co to dělá |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Generování obrázků** | `/v1/images/generations` s cloudovým a lokálním backendem |\n| 📐 **Vložení** | `/v1/embeddings` pro vyhledávání a RAG pipelines |\n| 🎤 **Přepis zvuku** | `/v1/audio/transcriptions` (Whisper a další poskytovatelé) |\n| 🔊 **Převod textu na řeč** | `/v1/audio/speech` (více enginů/poskytovatelů) |\n| 🎬 **Generování videa** | `/v1/videos/generations` (pracovní postupy ComfyUI + SD WebUI) |\n| 🎵 **Hudební generace** | `/v1/music/generations` (pracovní postupy ComfyUI) |\n| 🛡️ **Moderování** | Bezpečnostní kontroly `/v1/moderations` |\n| 🔀 **Změna pořadí** | `/v1/rerank` pro hodnocení relevance |\n| 🔍 **Vyhledávání na webu** 🆕 | `/v1/search` — 5 poskytovatelů (Serper, Brave, Perplexity, Exa, Tavily), více než 6 500 zdarma/měsíc, automatické přepnutí na záložní systém, mezipaměť |\n\n### 🛡️ Odolnost, bezpečnost a správa věcí veřejných\n\n| Funkce | Co to dělá |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| 🔌 **Jističe** | Vypnutí/obnovení pro každý model s ovládáním prahových hodnot |\n| 🎯 **Modely s ohledem na koncové body** | Vlastní modely deklarují podporované koncové body + formát API |\n| 🛡️ **Stádo proti hromům** | Ochrana mutexu a semaforu při událostech opakování/rychlosti |\n| 🧠 **Sémantická + podpisová mezipaměť** | Snížení nákladů/latence díky dvěma vrstvám mezipaměti |\n| ⚡ **Žádost o idempotenci** | Okno ochrany proti duplikacím |\n| 🔒 **Falšování otisků prstů pomocí TLS** | Otisk TLS podobný prohlížeči – **snižuje detekci botů a nahlašování účtů** |\n| 🔏 **Porovnávání otisků prstů v CLI** | Shoduje se s nativními podpisy požadavků CLI – **snižuje riziko zablokování a zároveň zachovává IP adresu proxy** |\n| 🌐 **Filtrování IP adres** | Ovládání seznamu povolených/blokovaných položek pro odhalená nasazení |\n| 📊 **Upravitelné limity rychlosti** | Konfigurovatelné globální/na úrovni poskytovatele limity s perzistencí |\n| 🔑 **Správa klíčů API a stanovení rozsahu** | Bezpečné vydávání/rotace klíčů a kontroly modelu/poskytovatele |\n| 🛡️ **Chráněné `/models`** | Volitelné ověřování a skrytí poskytovatele pro katalog modelů |\n\n### 📊 Pozorovatelnost a analytika\n\n| Funkce | Co to dělá |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| 📝 **Žádost + protokolování proxy** | Úplné protokolování požadavků/odpovědí a proxy |\n| 📋 **Sjednocený panel protokolů** | Zobrazení požadavků, proxy, auditu a konzole na jedné stránce |\n| 🔍 **Vyžádat si telemetrii** | Latence p50/p95/p99 a trasování požadavků |\n| 🏥 **Panel zdraví** | Doba provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti |\n| 💰 **Sledování nákladů** | Kontrola rozpočtu a přehled o cenách pro jednotlivé modely |\n| 📈 **Analytické vizualizace** | Přehledy využití modelů/poskytovatelů a zobrazení trendů |\n| 🧪 **Rámec hodnocení** | Testování zlaté sady s konfigurovatelnými strategiemi shody |\n\n### ☁️ Nasazení a platforma\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| 🌐 **Nasazení kdekoli** | Localhost, VPS, Docker, cloudová prostředí |\n| 💾 **Synchronizace s cloudem** | Synchronizace konfigurace přes cloud worker |\n| 🔄 **Zálohování/Obnovení** | Toky exportu/importu a obnovy po havárii |\n| 🧙 **Průvodce nástupem** | Průvodce prvním spuštěním |\n| 🔧 **Panel nástrojů CLI** | Nastavení oblíbených kódovacích nástrojů jedním kliknutím |\n| 🎮 **Modelové hřiště** | Otestujte libovolného poskytovatele/model/koncový bod z řídicího panelu |\n| 🔏 **Přepínač otisků prstů v příkazovém řádku** | Porovnávání otisků prstů podle poskytovatele v Nastavení &gt; Zabezpečení |\n| 🌐 **i18n (30 jazyků)** | Plná jazyková podpora dashboardu a dokumentace s psaním zprava doleva |\n| 📂 **Adresář vlastních dat** | Přepsání `DATA_DIR` pro umístění úložiště |\n\n### Hluboký pohled na funkce\n\n#### Chytrá záložní funkce s praktickou kontrolou nákladů\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyž selže kvóta, rychlost nebo stav, OmniRoute automaticky přejde k dalšímu kandidátovi bez nutnosti ručního přepínání.\n\n#### Správa protokolů, která je viditelná a ovladatelná\n\n- MCP + A2A jsou viditelné v uživatelském rozhraní a dokumentaci (nejsou skryté)\n- API pro stav protokolu zpřístupňují živá provozní data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnují akce pro operace 2. dne (přepínání kombinací, resetování jističů, zrušení úkolů)\n\n#### Pracovní postup překladatele + validace\n\nOblast překladatele zahrnuje:\n\n- **Hřiště** : kontroly transformace požadavků\n- **Tester chatu** : kompletní okružní cesta požadavku/odpovědi\n- **Testovací stolice** : více případů v jednom běhu\n- **Živý monitor** : zobrazení provozu v reálném čase\n\nPlus validace protokolu se skutečnými klienty pomocí `npm run test:protocols:e2e` .\n\n> 📖 **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** — Referenční informace o nástrojích, konfigurace IDE a příklady klientů\n>\n> 📖 **[Soubor README pro A2A Server](src/lib/a2a/README.md)** — Dovednosti, metody JSON-RPC, streamování a životní cyklus úloh\n\n## 🧪 Hodnocení (Evals)\n\nOmniRoute obsahuje vestavěný hodnotící rámec pro testování kvality odpovědí LLM v porovnání se zlatou sadou. Přístup k němu je možný přes **Analýzy → Hodnocení** v dashboardu.\n\n### Vestavěná zlatá sada\n\nPředinstalovaná sada „OmniRoute Golden Set“ obsahuje testovací případy pro:\n\n- Zdravím, matematika, zeměpis, generování kódu\n- Shoda s formátem JSON, překlad, generování markdownů\n- Bezpečnostní odmítnutí (škodlivý obsah), počítání, booleovská logika\n\n### Strategie hodnocení\n\n| Strategie | Popis | Příklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Výstup se musí přesně shodovat | `\"4\"` |\n| `contains` | Výstup musí obsahovat podřetězec (bez rozlišení velkých a malých písmen) | `\"Paris\"` |\n| `regex` | Výstup musí odpovídat vzoru regulárních výrazů | `\"1.*2.*3\"` |\n| `custom` | Vlastní JS funkce vrací true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Průvodce nastavením\n\n### Nastavení protokolu (MCP + A2A)\n\n<details>\n<summary><b>🧩 Nastavení MCP (Model Context Protocol)</b></summary>\n</details>\n\nSpuštění MCP transportu v režimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporučený postup ověření:\n\n1. Připojte svého MCP klienta přes stdio.\n2. Spusťte `omniroute_get_health` .\n3. Spusťte `omniroute_list_combos` .\n4. Otevřete `/dashboard/mcp` pro ověření prezenčního signálu, aktivity a auditu.\n\nUžitečná API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n<details>\n<summary><b>🤝 Nastavení A2A (Agent2Agent)</b></summary>\n</details>\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat úkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSpráva životního cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvozní uživatelské rozhraní:\n\n- `/dashboard/a2a` pro pozorovatelnost úloh/stavů/streamů a akce kouření\n\n<details>\n<summary><b>🧪 Komplexní validace protokolu</b></summary>\n</details>\n\nOvěřte oba protokoly se skutečnými klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTím se ověřuje:\n\n- Připojení/seznam/volání klienta MCP SDK\n- A2A objevování/odesílání/streamování/získávání/zrušení\n- Křížová kontrola dat v auditu MCP a API pro správu úloh A2A\n\n<details>\n<summary><b>💳 Poskytovatelé předplatného</b></summary>\n</details>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionály:** Pro složité úkoly používejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvótu pro každý model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Správa limitů účtu Codex (5h + týdně)\n\nKaždý účet Codex má nyní přepínače zásad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinového prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zásadu týdenního prahu okna.\n- Prahové chování: když povolené okno dosáhne využití &gt;=90 %, je daný účet přeskočen.\n- Chování rotace: OmniRoute automaticky přesměruje na další způsobilý účet Codex.\n- Chování při resetování: Po `resetAt` určité doby se účet automaticky opět stane způsobilým.\n\nScénáře:\n\n- `5h ON` + `Weekly ON` : účet je přeskočen, když kterékoli z oken dosáhne prahové hodnoty.\n- `5h OFF` + `Weekly ON` : účet může být zablokován pouze týdenním používáním.\n- `5h ON` + `Weekly OFF` : účet může být zablokován pouze při 5hodinovém používání.\n- `resetAt` passed: účet se automaticky znovu zapne (bez ručního opětovného povolení).\n\n### Gemini CLI (ZDARMA 180 000/měsíc!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepší hodnota:** Obrovská bezplatná úroveň! Použijte ji před placenými úrovněmi.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n<details>\n<summary><b>🔑 Poskytovatelé klíčů API</b></summary>\n</details>\n\n### NVIDIA NIM (BEZPLATNÝ přístup pro vývojáře — více než 70 modelů)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Získejte zdarma klíč API (včetně 1000 inferenčních kreditů)\n3. Ovládací panel → Přidat poskytovatele → NVIDIA NIM:\n - Klíč API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a více než 50 dalších\n\n**Tip pro profesionály:** API kompatibilní s OpenAI – funguje bez problémů s překladem formátů OmniRoute!\n\n### Hluboké vyhledávání\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatná úroveň!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Získejte klíč API (včetně bezplatné úrovně)\n3. Ovládací panel → Přidat poskytovatele → Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionály:** Ultrarychlá inference – nejlepší pro kódování v reálném čase!\n\n### OpenRouter (100+ modelů)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → OpenRouter\n\n**Modely:** Získejte přístup k více než 100 modelům od všech hlavních poskytovatelů prostřednictvím jediného klíče API.\n\n<details>\n<summary><b>💰 Levní poskytovatelé (záložní)</b></summary>\n</details>\n\n### GLM-4.7 (Denní reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Získejte klíč API z kódovacího plánu\n3. Nástěnka → Přidat klíč API:\n - Poskytovatel: `glm`\n - Klíč API: `your-key`\n\n**Použití:** `glm/glm-4.7`\n\n**Tip pro profesionály:** Programovací plán nabízí 3× kvótu za cenu 1/7! Obnovuje se denně v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionály:** Nejlevnější varianta pro dlouhý kontext (1 milion tokenů)!\n\n### Kimi K2 (paušální poplatek 9 dolarů měsíčně)\n\n1. Odebírat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `kimi/kimi-latest`\n\n**Tip pro profesionály:** Fixních 9 $/měsíc za 10 milionů tokenů = efektivní náklady 0,90 $/1 milion!\n\n<details>\n<summary><b>🆓 BEZPLATNÍ poskytovatelé (nouzové zálohování)</b></summary>\n</details>\n\n### iFlow (5 BEZPLATNÝCH modelů přes OAuth)\n\n```bash\nDashboard → Connect iFlow\n→ iFlow OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kódem zařízení)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n<details>\n<summary><b>🎨 Vytvořte kombinace</b></summary>\n</details>\n\n### Příklad 1: Maximalizace předplatného → Levné zálohování\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Příklad 2: Pouze zdarma (nulové náklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n<details>\n<summary><b>🔧 Integrace s rozhraním příkazového řádku</b></summary>\n</details>\n\n### IDE kurzoru\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jedním kliknutím použijte stránku **Nástroje CLI** na řídicím panelu nebo ručně upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Možnost 1 – Dashboard (doporučeno):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Možnost 2 – Manuální úprava:** Úprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznámka:** OpenClaw funguje pouze s lokálním OmniRoute. Místo `localhost` použijte `127.0.0.1` , abyste se vyhnuli problémům s rozlišením IPv6.\n\n### Cline / Pokračovat / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Přidání OmniRoute jako vlastního poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvořte/upravte `opencode.json` v kořenovém adresáři projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` přidejte jakýkoli model dostupný ve vašem koncovém bodu OmniRoute `/v1/models` . Použijte formát `provider/model-id` z vašeho dashboardu OmniRoute.\n\n---\n\n## 🐛 Řešení problémů\n\n<details>\n<summary><b>Kliknutím rozbalíte průvodce řešením problémů</b></summary>\n</details>\n\n**\"Jazykový model neposkytoval zprávy\"**\n\n- Kvóta poskytovatele vyčerpána → Zkontrolujte sledování kvót na řídicím panelu\n- Řešení: Použijte záložní kombinovanou variantu nebo přejděte na levnější úroveň\n\n**Omezení rychlosti**\n\n- Kvóta předplatného vyčerpána → Přechod na GLM/MiniMax\n- Přidat kombo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vypršela**\n\n- Automaticky aktualizováno službou OmniRoute\n- Pokud problémy přetrvávají: Ovládací panel → Poskytovatel → Znovu připojit\n\n**Vysoké náklady**\n\n- Zkontrolujte statistiky využití v sekci Nástěnka → Náklady\n- Přepnout primární model na GLM/MiniMax\n- Pro nekritické úlohy použijte bezplatnou úroveň (Gemini CLI, iFlow).\n\n**Porty řídicího panelu/API jsou nesprávné**\n\n- `PORT` je kanonický základní port (a standardně port API)\n- `API_PORT` přepisuje pouze posluchač API kompatibilní s OpenAI.\n- `DASHBOARD_PORT` přepisuje pouze posluchač dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaši veřejnou URL adresu řídicího panelu (pro zpětná volání OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ověřte, zda `BASE_URL` odkazuje na vaši spuštěnou instanci.\n- Ověřte, zda `CLOUD_URL` odkazuje na váš očekávaný cloudový koncový bod.\n- Udržujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na straně serveru.\n\n**První přihlášení nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud není nastaveno, záložní heslo je `123456`\n\n**Žádné protokoly požadavků**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test připojení ukazuje „Neplatné“ pro poskytovatele kompatibilní s OpenAI**\n\n- Mnoho poskytovatelů nezpřístupňuje koncový bod `/models`\n- OmniRoute v1.0.6+ zahrnuje záložní ověření pomocí dokončení chatu\n- Zajistěte, aby základní URL adresa obsahovala příponu `/v1`\n\n### 🔐 OAuth na vzdáleném serveru\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Důležité pro uživatele, kteří provozují OmniRoute na VPS, Dockeru nebo jakémkoli vzdáleném serveru**\n\n#### Proč selhává OAuth v rozhraní CLI Antigravity / Gemini na vzdálených serverech?\n\nPoskytovatelé rozhraní CLI **Antigravity** a **Gemini** používají **Google OAuth 2.0** . Google vyžaduje, aby se `redirect_uri` v toku OAuth přesně shodoval s jedním z předregistrovaných URI v konzoli Google Cloud Console aplikace.\n\nPřihlašovací údaje OAuth, které jsou součástí OmniRoute, jsou registrovány **pouze pro `localhost`** . Když přistupujete k OmniRoute na vzdáleném serveru (např. `https://omniroute.myserver.com` ), Google odmítne ověření pomocí:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Řešení: Nakonfigurujte si vlastní přihlašovací údaje OAuth\n\nV Google Cloud Console je potřeba vytvořit **ID klienta OAuth 2.0** s URI vašeho serveru.\n\n#### Krok za krokem\n\n**1. Otevřete konzoli Google Cloud**\n\nPřejděte na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvořte nové ID klienta OAuth 2.0**\n\n- Klikněte na **„+ Vytvořit přihlašovací údaje“** → **„ID klienta OAuth“**\n- Typ aplikace: **„Webová aplikace“**\n- Název: cokoli chcete (např. `OmniRoute Remote` )\n\n**3. Přidejte autorizované URI pro přesměrování**\n\nDo pole **„Autorizované identifikátory URI pro přesměrování“** přidejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraďte `your-server.com` doménou nebo IP adresou vašeho serveru (v případě potřeby uveďte i port, např. `http://45.33.32.156:20128/callback` ).\n\n**4. Uložte a zkopírujte přihlašovací údaje**\n\nPo vytvoření Google zobrazí **ID klienta** a **tajný kód klienta** .\n\n**5. Nastavení proměnných prostředí**\n\nVe vašem souboru `.env` (nebo proměnných prostředí Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu připojit**\n\nŘídicí panel → Poskytovatelé → Antigravity (nebo Gemini CLI) → OAuth\n\nGoogle nyní bude správně přesměrovávat na `https://your-server.com/callback` .\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nPokud si teď nechcete nastavovat vlastní přihlašovací údaje, můžete stále použít **ruční postup pro URL** :\n\n1. OmniRoute otevírá autorizační URL od Googlu\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru).\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče (i když se stránka nenačte)\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute.\n5. Klikněte na **„Připojit“**\n\n> To funguje, protože autorizační kód v URL adrese je platný bez ohledu na to, zda se načetla přesměrovací stránka.\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nChcete-li získat přístup k přihlašovacím údajům bez vlastní konfigurace, můžete použít následující postup:\n\n1. OmniRoute otevře URL autorizace Google\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru)\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute\n5. Klikněte na **„Připojit\"**\n\n> Toto řešení funguje, protože autorizační kód v URL adrese je platný bez ohledu na načtení přesměrovací stránky.\n\n---\n\n## 🛠️ Technologický stack\n\n<details>\n<summary><b>Kliknutím rozbalíte podrobnosti o technologickém stacku</b></summary>\n</details>\n\n- **Runtime** : Node.js 18–22 LTS (⚠️ Node.js 24+ **není podporován** — nativní binární soubory `better-sqlite3` jsou nekompatibilní)\n- **Jazyk** : TypeScript 5.9 — **100% TypeScript** napříč `src/` a `open-sse/` ( `any` v základních modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databáze** : LowDB (JSON) + SQLite (stav domény + protokoly proxy + audit MCP + rozhodnutí o směrování)\n- **Schémata** : Zod (validace I/O nástrojů MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamování** : Události odeslané serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klíče + autorizace s rozsahem MCP\n- **Testování** : Node.js test runner + Vitest (900+ testů včetně unit, integračních, E2E)\n- **CI/CD** : Akce GitHubu (automatické publikování v npm + Docker Hub při vydání)\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **Balíček** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistič, exponenciální odstavení, ochrana proti hromům, falešné TLS, automatické kombinované samoopravování\n\n---\n\n## 📖 Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uživatelská příručka](docs/USER_GUIDE.md) | Poskytovatelé, kombinace, integrace CLI, nasazení |\n| [Referenční informace k API](docs/API_REFERENCE.md) | Všechny koncové body s příklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nástrojů MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamování, správa úloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorové bodování, balíčky režimů, samoléčba |\n| [Odstraňování problémů](docs/TROUBLESHOOTING.md) | Běžné problémy a jejich řešení |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a interní prvky systému |\n| [Přispívání](CONTRIBUTING.md) | Nastavení a pokyny pro vývoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpečnostní zásady](SECURITY.md) | Hlášení zranitelností a bezpečnostní postupy |\n| [Nasazení virtuálního počítače](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletní průvodce: Nastavení virtuálního počítače + nginx + Cloudflare |\n| [Galerie funkcí](docs/FEATURES.md) | Vizuální prohlídka řídicího panelu se snímky obrazovky |\n| [Kontrolní seznam vydání](docs/RELEASE_CHECKLIST.md) | Kroky ověření před vydáním |\n\n---\n\n## 🗺️ Plán\n\nOmniRoute má **v plánu více než 210 funkcí** v několika fázích vývoje. Zde jsou klíčové oblasti:\n\n| Kategorie | Plánované funkce | Hlavní body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| 🧠 **Směrování a inteligence** | 25+ | Směrování s nejnižší latencí, směrování založené na tagech, kontrola kvót před výstupem, výběr účtu P2C |\n| 🔒 **Zabezpečení a dodržování předpisů** | 20+ | Zpevnění SSRF, maskování přihlašovacích údajů, limit rychlosti pro každý koncový bod, stanovení rozsahu klíčů pro správu |\n| 📊 **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledování kvót v reálném čase, sledování nákladů podle modelu |\n| 🔄 **Integrace poskytovatelů** | 20+ | Dynamický registr modelů, doba zchlazení poskytovatelů, Codex pro více účtů, analýza kvót Copilota |\n| ⚡ **Výkon** | 15+ | Dvojitá vrstva mezipaměti, mezipaměť výzev, mezipaměť odpovědí, udržování streamování, dávkové API |\n| 🌐 **Ekosystém** | 10+ | WebSocket API, horké opětovné načítání konfigurace, distribuované úložiště konfigurace, komerční režim |\n\n### 🔜 Již brzy\n\n- 🔗 **Integrace OpenCode** — Nativní podpora poskytovatelů pro IDE kódování s AI v OpenCode\n- 🔗 **Integrace TRAE** — Plná podpora vývojového rámce TRAE pro umělou inteligenci\n- 📦 **Dávkové API** — Asynchronní dávkové zpracování hromadných požadavků\n- 🎯 **Směrování na základě tagů** — Směrování požadavků na základě vlastních tagů a metadat\n- 💰 **Strategie nejnižších nákladů** – Automaticky vybere nejlevnějšího dostupného poskytovatele\n\n> 📝 Úplné specifikace funkcí jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobných specifikací)\n\n---\n\n## 👥 Přispěvatelé\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Přispěvatelé](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak přispět\n\n1. Vytvoření forku repozitáře\n2. Vytvořte si vlastní větev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrďte změny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do větve ( `git push origin feature/amazing-feature` )\n5. Otevřít žádost o změny (pull request)\n\nPodrobné pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydání nové verze\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Hvězdná historie\n\n## Hvězdáři v průběhu času\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvězdáři v průběhu času](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## 🙏 Poděkování\n\nZvláštní poděkování patří **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** – původnímu projektu, který inspiroval tento fork. OmniRoute staví na tomto neuvěřitelném základu s dalšími funkcemi, multimodálními API a kompletním přepsáním TypeScriptu.\n\nZvláštní poděkování patří **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – původní implementaci Go, která inspirovala tento JavaScriptový port.\n\n---\n\n## 📄 Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n<div align=\"center\">\n <sub>Vytvořeno s ❤️ pro vývojáře, kteří programují 24 hodin denně, 7 dní v týdnu</sub>\n <br>\n <sub><p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\">omniroute.online</a></p></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "b5a145d7b336ce90a238db309951c57a508fb564": {"t": 1785764469.5980096, "n": 94491, "h": "9be6d6b894b577e6", "c": "# 🚀 OmniRoute — Bezplatná brána umělé inteligence\n\n### Nikdy nepřestávejte s kódováním. Chytré směrování k **BEZPLATNÝM a levným modelům AI** s automatickým přepínáním mezi záložními systémy.\n\n_Váš univerzální API proxy – jeden endpoint, více než 44 poskytovatelů, nulové výpadky. Nyní s orchestrací agentů **MCP a A2A** ._\n\n**Dokončení chatu • Vkládání • Generování obrázků • Video • Hudba • Audio • Změna pořadí • **Vyhledávání na webu** • MCP server • A2A protokol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n</div>\n<p data-md-type=\"paragraph\"><a href=\"https://www.npmjs.com/package/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/npm/v/omniroute?color=cb3837&amp;logo=npm\" alt=\"verze npm\" data-md-type=\"image\"><a href=\"https://hub.docker.com/r/diegosouzapw/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&amp;logo=docker&amp;color=2496ED\" alt=\"Docker Hub\" data-md-type=\"image\"><a href=\"https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/github/license/diegosouzapw/OmniRoute\" alt=\"Licence\" data-md-type=\"image\"><a href=\"https://omniroute.online\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&amp;logoColor=white\" alt=\"Webové stránky\" data-md-type=\"image\"><a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&amp;logoColor=white\" alt=\"WhatsApp\" data-md-type=\"image\"></p>\n<p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\" data-md-type=\"link\">🌐 Webové stránky</a> • <a href=\"#-quick-start\" data-md-type=\"link\">🚀 Rychlý start</a> • <a href=\"#-key-features\" data-md-type=\"link\">💡 Funkce</a> • <a href=\"#-documentation\" data-md-type=\"link\">📖 Dokumentace</a> • <a href=\"#-pricing-at-a-glance\" data-md-type=\"link\">💰 Ceník</a> • <a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\">💬 WhatsApp</a></p>\n<div data-md-type=\"block_html\"></div>\n\n🌐 **Dostupné v:** 🇺🇸 [Angličtina](README.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [maďarština](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonésie](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nizozemsko](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)\n\n---\n\n## 🖼️ Hlavní ovládací panel\n\n<div align=\"center\"> <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"Řídicí panel OmniRoute\" width=\"800\"> </div>\n\n---\n\n## 📸 Náhled řídicího panelu\n\n<details>\n<summary><b>Kliknutím zobrazíte snímky obrazovky z řídicího panelu</b></summary>\n</details>\n\n| Strana | Snímek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelé** | ![Poskytovatelé](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdraví** | ![Zdraví](docs/screenshots/04-health.png) |\n| **Překladatel** | ![Překladatel](docs/screenshots/05-translator.png) |\n| **Nastavení** | ![Nastavení](docs/screenshots/06-settings.png) |\n| **Nástroje CLI** | ![Nástroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly používání** | ![Používání](docs/screenshots/08-usage.png) |\n| **Koncové body** | ![Koncové body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### 🤖 Bezplatný poskytovatel umělé inteligence pro vaše oblíbené programátory\n\n_Připojte libovolný nástroj IDE nebo CLI s umělou inteligencí přes OmniRoute — bezplatnou API bránu pro neomezené kódování._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openclaw/openclaw\"><img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"><br><b>OpenClaw</b></a><br> <sub>⭐ 205 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/HKUDS/nanobot\"><img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"><br><b>NanoBot</b></a><br> <sub>⭐ 20,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/sipeed/picoclaw\"><img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"><br><b>PicoClaw</b></a><br> <sub>⭐ 14,6 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/zeroclaw-labs/zeroclaw\"><img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"><br><b>ZeroClaw</b></a><br> <sub>⭐ 9,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/nearai/ironclaw\"><img src=\"./public/providers/ironclaw.png\" alt=\"Železný dráp\" width=\"48\"><br><b>Železný dráp</b></a><br> <sub>⭐ 2,1 tisíce</sub> </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anomalyco/opencode\"><img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"><br><b>OpenCode</b></a><br> <sub>⭐ 106 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openai/codex\"><img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"><br><b>Codex CLI</b></a><br> <sub>⭐ 60,8 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anthropics/claude-code\"><img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"><br><b>Claude Code</b></a><br> <sub>⭐ 67,3 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/google-gemini/gemini-cli\"><img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"><br> <b>Gemini CLI</b></a><br> <sub>⭐ 94,7 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/Kilo-Org/kilocode\"><img src=\"./public/providers/kilocode.png\" alt=\"Kilo kód\" width=\"48\"><br><b>Kilo kód</b></a><br> <sub>⭐ 15,5 tisíc</sub> </td>\n </tr>\n </table>\n\n<sub>📡 Všichni agenti se připojují přes <code>http://localhost:20128/v1</code> nebo <code>http://cloud.omniroute.online/v1</code> — jedna konfigurace, neomezené modely a kvóty</sub>\n\n---\n\n## 🤔 Proč OmniRoute?\n\n**Přestaňte plýtvat penězi a narážet na limity:**\n\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Kvóta předplatného vyprší každý měsíc\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Limity rychlosti vám zabrání v kódování\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Drahá API (20–50 USD/měsíc na poskytovatele)\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Ruční přepínání mezi poskytovateli\n\n**OmniRoute to řeší:**\n\n- ✅ **Maximalizujte předplatné** – Sledujte kvótu, využijte každou částku před resetováním\n- ✅ **Automatické záložní** – Předplatné → API klíč → Levné → Zdarma, žádné výpadky\n- ✅ **Více účtů** – Round-robin mezi účty u jednotlivých poskytovatelů\n- ✅ **Univerzální** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakýmkoli nástrojem CLI\n\n---\n\n## 📧 Podpora\n\n> 💬 **Přidejte se k naší komunitě!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získejte pomoc, sdílejte tipy a buďte v obraze.\n\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problémy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitní skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Přispívání** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevřete žádost o příspěvek nebo si vyberte `good first issue`\n- **Původní projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### 🐛 Hlásíte chybu?\n\nPři otevírání problému spusťte příkaz system-info a přiložte vygenerovaný soubor:\n\n```bash\nnpm run system-info\n```\n\nTím se vygeneruje soubor `system-info.txt` s verzí Node.js, verzí OmniRoute, podrobnostmi o operačním systému, nainstalovanými nástroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systémovými balíčky – vše, co potřebujeme k rychlé reprodukci vašeho problému. Soubor přiložte přímo k vašemu problému na GitHubu.\n\n---\n\n## 🔄 Jak to funguje\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 Co řeší OmniRoute — 30 skutečných problémů a případů použití\n\n> **Každý vývojář používající nástroje umělé inteligence se s těmito problémy setkává denně.** OmniRoute byl vytvořen tak, aby je všechny vyřešil – od překročení nákladů po regionální bloky, od nefunkčních toků OAuth až po operace s protokoly a sledovatelnost v podniku.\n\n<details>\n<summary><b>💸 1. „Platím si drahé předplatné, ale stále mě ruší limity“</b></summary>\n</details>\n\nVývojáři platí za Claude Pro, Codex Pro nebo GitHub Copilot 20–200 dolarů měsíčně. I při platbě má kvóta strop – 5 hodin používání, týdenní limity nebo limity rychlosti za minutu. Uprostřed kódovací relace poskytovatel přestane reagovat a vývojář ztrácí plynulost a produktivitu.\n\n**Jak to OmniRoute řeší:**\n\n- **Inteligentní čtyřúrovňová záložní služba** – Pokud dojde kvóta předplatného, ​​automaticky se přesměruje na API klíč → Levné → Zdarma bez manuálního zásahu\n- **Sledování kvót v reálném čase** – Zobrazuje spotřebu tokenů v reálném čase s odpočítáváním resetování (5 hodin, denně, týdně)\n- **Podpora více účtů** – Více účtů u jednoho poskytovatele s automatickým přepínáním – když jeden dojde, přepne se na další\n- **Vlastní kombinace** — Přizpůsobitelné záložní řetězce se 6 strategiemi vyvažování (fill-first, round robin, P2C, náhodné, nejméně používané, nákladově optimalizované)\n- **Codex Business Quotas** — Sledování kvót pracovního prostoru firmy/týmu přímo v dashboardu\n\n<details>\n<summary><b>🔌 2. „Potřebuji použít více poskytovatelů, ale každý má jiné API“</b></summary>\n</details>\n\nOpenAI používá jeden formát, Claude (Anthropic) jiný a Gemini ještě třetí. Pokud chce vývojář testovat modely od různých poskytovatelů nebo mezi nimi přecházet, musí překonfigurovat SDK, změnit koncové body a vypořádat se s nekompatibilními formáty. Vlastní poskytovatelé (FriendLI, NIM) mají nestandardní koncové body modelů.\n\n**Jak to OmniRoute řeší:**\n\n- **Sjednocený koncový bod** — Jeden `http://localhost:20128/v1` slouží jako proxy pro všech 44+ poskytovatelů.\n- **Překlad formátu** — Automatický a transparentní: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Sanitizace odpovědí** — Odstraňuje nestandardní pole ( `x_groq` , `usage_breakdown` , `service_tier` ), která porušují OpenAI SDK v1.83+\n- **Normalizace rolí** — Převádí `developer` → `system` pro poskytovatele bez OpenAI; `system` → `user` pro GLM/ERNIE\n- **Extrakce tagů Think** — Extrahuje bloky `<think>` z modelů, jako je DeepSeek R1, do standardizovaného `reasoning_content`\n- **Strukturovaný výstup pro Gemini** — `json_schema` → automatická konverze `responseMimeType` / `responseSchema`\n- **Výchozí hodnota `stream` je `false`** – Odpovídá specifikaci OpenAI, čímž se zabrání neočekávanému SSE v Python/Rust/Go SDK.\n\n<details>\n<summary><b>🌐 3. „Můj poskytovatel AI blokuje můj region/zemi“</b></summary>\n</details>\n\nPoskytovatelé jako OpenAI/Codex blokují přístup z určitých geografických oblastí. Uživatelé se během připojení OAuth a API dostávají k chybám jako `unsupported_country_region_territory` . To je obzvláště frustrující pro vývojáře z rozvojových zemí.\n\n**Jak to OmniRoute řeší:**\n\n- **3úrovňová konfigurace proxy** – Konfigurovatelná proxy na 3 úrovních: globální (veškerý provoz), pro jednotlivé poskytovatele (pouze jeden poskytovatel) a pro jednotlivé připojení/klíč\n- **Barevně kódované odznaky proxy** – Vizuální indikátory: 🟢 globální proxy, 🟡 proxy poskytovatele, 🔵 proxy připojení, vždy zobrazující IP adresu\n- **Výměna tokenů OAuth prostřednictvím proxy** – tok OAuth také prochází přes proxy, čímž se řeší `unsupported_country_region_territory`\n- **Testy připojení přes proxy** – Testy připojení používají nakonfigurovaný proxy (již žádné přímé obcházení)\n- **Podpora SOCKS5** — Plná podpora proxy SOCKS5 pro odchozí směrování\n- **TLS Fingerprint Spoofing** — Otisk prstu TLS podobný prohlížeči pomocí `wreq-js` pro obcházení detekce botů\n- **🔏 Porovnávání otisků prstů v CLI** — Změní pořadí záhlaví a polí v těle serveru tak, aby odpovídala nativním binárním podpisům v CLI, čímž drasticky snižuje riziko nahlašování účtu. IP adresa proxy je zachována — získáte současně stealth **i** maskování IP adresy.\n\n<details>\n<summary><b>🆓 4. „Chci používat umělou inteligenci pro kódování, ale nemám peníze“</b></summary>\n</details>\n\nNe každý si může dovolit zaplatit 20–200 dolarů měsíčně za předplatné AI. Studenti, vývojáři z rozvíjejících se zemí, amatéři a freelanceři potřebují přístup ke kvalitním modelům za nulovou cenu.\n\n**Jak to OmniRoute řeší:**\n\n- **Vestavění poskytovatelé bezplatné úrovně** — Nativní podpora pro 100% bezplatné poskytovatele: iFlow (5 neomezených modelů přes OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezené modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisíc tokenů/měsíc zdarma)\n- **Ollama Cloud** — Cloudově hostované modely Ollama na `api.ollama.com` s bezplatnou úrovní „Light usage“; použijte prefix `ollamacloud/<model>`\n- **Kombinace pouze zdarma** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/měsíc s nulovými prostoji\n- **NVIDIA NIM Free Access** — ~40 RPM developerský přístup k více než 70 modelům na build.nvidia.com (přechod z kreditů na čisté limity rychlosti)\n- **Strategie optimalizace nákladů** – Strategie směrování, která automaticky vybere nejlevnějšího dostupného poskytovatele\n\n<details>\n<summary><b>🔒 5. „Potřebuji chránit svou bránu umělé inteligence před neoprávněným přístupem“</b></summary>\n</details>\n\nPři zpřístupnění brány umělé inteligence síti (LAN, VPS, Docker) může kdokoli s adresou spotřebovat tokeny/kvótu vývojáře. Bez ochrany jsou API zranitelná vůči zneužití, prompt injection a dalšímu zneužití.\n\n**Jak to OmniRoute řeší:**\n\n- **Správa klíčů API** – generování, rotace a vymezování rozsahu pro každého poskytovatele s vyhrazenou stránkou `/dashboard/api-manager`\n- **Oprávnění na úrovni modelu** – Omezení klíčů API na konkrétní modely ( `openai/*` , zástupné znaky) pomocí přepínače Povolit vše/Omezit\n- **Ochrana koncových bodů API** – Vyžaduje klíč pro `/v1/models` a blokuje konkrétní poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** — Všechny trasy dashboardu chráněné middlewarem `withAuth` + tokeny CSRF\n- **Omezovač rychlosti** — Omezování rychlosti na IP s konfigurovatelnými okny\n- **Filtrování IP adres** — Seznam povolených/blokovaných adres pro řízení přístupu\n- **Ochrana proti vkládání výzev** – Sanitizace proti škodlivým vzorcům výzev\n- **Šifrování AES-256-GCM** – přihlašovací údaje jsou v klidovém stavu šifrovány\n\n<details>\n<summary><b>🛑 6. „Můj poskytovatel selhal a já ztratil/a programovací tok“</b></summary>\n</details>\n\nPoskytovatelé umělé inteligence se mohou stát nestabilními, vracet chyby 5xx nebo dosáhnout dočasných limitů rychlosti. Pokud je vývojář závislý na jediném poskytovateli, je jeho práce přerušena. Bez jističů může opakované pokusy vést k pádu aplikace.\n\n**Jak to OmniRoute řeší:**\n\n- **Jistič pro každý model** – Automatické otevírání/zavírání s konfigurovatelnými prahovými hodnotami a dobou ochlazování (Zavřeno/Otevřeno/Poloviční otevření), rozsah definovaný pro každý model, aby se zabránilo kaskádování bloků\n- **Exponenciální odklad** — Progresivní zpoždění opakování\n- **Anti-Thundering Herd** — ochrana Mutex + semafor proti souběžným bouřím s opakovanými pokusy\n- **Kombinované záložní řetězce** – Pokud primární poskytovatel selže, automaticky se propadne řetězcem bez zásahu.\n- **Kombinovaný jistič** – Automaticky deaktivuje selhávajícího poskytovatele v rámci kombinovaného řetězce\n- **Dashboard stavu** — Monitorování provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti, latence p50/p95/p99\n\n<details>\n<summary><b>🔧 7. „Konfigurace každého nástroje umělé inteligence je zdlouhavá a opakující se“</b></summary>\n</details>\n\nVývojáři používají Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Každý nástroj potřebuje jinou konfiguraci (API endpoint, klíč, model). Překonfigurování při změně poskytovatele nebo modelu je ztráta času.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel nástrojů CLI** — Vyhrazená stránka s nastavením jedním kliknutím pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generátor konfigurace GitHub Copilot** – Generuje `chatLanguageModels.json` pro VS Code s hromadným výběrem modelu\n- **Průvodce zaváděním** – 4krokové nastavení pro začínající uživatele\n- **Jeden koncový bod, všechny modely** – jednou nakonfigurujte `http://localhost:20128/v1` a získejte přístup k více než 44 poskytovatelům\n\n<details>\n<summary><b>🔑 8. „Správa OAuth tokenů od více poskytovatelů je peklo“</b></summary>\n</details>\n\nClaude Code, Codex, Gemini CLI, Copilot – všechny používají OAuth 2.0 s tokeny s vypršením platnosti. Vývojáři se musí neustále znovu autentizovat, řešit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdálených serverech. Obzvláště problematický je OAuth v LAN/VPS.\n\n**Jak to OmniRoute řeší:**\n\n- **Automatická aktualizace tokenů** – Tokeny OAuth se obnovují na pozadí před vypršením platnosti.\n- **Vestavěný OAuth 2.0 (PKCE)** – Automatický tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** — Více účtů na poskytovatele prostřednictvím extrakce tokenů JWT/ID\n- **OAuth LAN/Remote Fix** — Detekce privátní IP adresy pro `redirect_uri` + manuální režim URL pro vzdálené servery\n- **OAuth Behind Nginx** — Používá `window.location.origin` pro kompatibilitu s reverzní proxy\n- **Průvodce vzdáleným OAuth** – Podrobný návod k přihlašovacím údajům Google Cloud na VPS/Dockeru\n\n<details>\n<summary><b>📊 9. „Nevím, kolik utrácím ani kde“</b></summary>\n</details>\n\nVývojáři používají více placených poskytovatelů, ale nemají jednotný přehled o výdajích. Každý poskytovatel má svůj vlastní fakturační panel, ale neexistuje žádný konsolidovaný přehled. Mohou se hromadit neočekávané náklady.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard pro analýzu nákladů** – Sledování nákladů na token a správa rozpočtu pro každého poskytovatele\n- **Rozpočtové limity na úroveň** – Strop výdajů na úroveň, který spouští automatický záložní režim\n- **Konfigurace cen podle modelu** – Konfigurovatelné ceny podle modelu\n- **Statistiky použití pro každý klíč API** — Počet požadavků a časové razítko posledního použití pro každý klíč\n- **Analytický panel** – Statistické karty, graf využití modelu, tabulka poskytovatelů s mírou úspěšnosti a latencí\n\n<details>\n<summary><b>🐛 10. „Nedokážu diagnostikovat chyby a problémy ve volání umělé inteligence.“</b></summary>\n</details>\n\nKdyž volání selže, vývojář neví, zda se jednalo o limit rychlosti, vypršelý token, špatný formát nebo chybu poskytovatele. Fragmentované protokoly napříč různými terminály. Bez sledovatelnosti je ladění metodou pokus-omyl.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel jednotných protokolů** – 4 karty: Protokoly požadavků, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlížeč protokolů konzole** — Prohlížeč protokolů v reálném čase ve stylu terminálu s barevně kódovanými úrovněmi, automatickým posouváním, vyhledáváním a filtrováním\n- **Protokoly proxy SQLite** – trvalé protokoly, které přežijí restart serveru\n- **Překladačské hřiště** — 4 režimy ladění: Hřiště (překlad formátu), Tester chatu (okružní), Testovací stůl (dávkový), Živý monitor (v reálném čase)\n- **Telemetrie požadavků** — latence p50/p95/p99 + trasování X-Request-Id\n- **Souborové protokolování s rotací** – Konzolový interceptor zachycuje vše do protokolu JSON s rotací na základě velikosti\n- **Zpráva o systémových informacích** — příkaz `npm run system-info` vygeneruje `system-info.txt` s kompletním popisem vašeho prostředí (verze uzlu, verze OmniRoute, operační systém, nástroje CLI, stav Dockeru/PM2). Přiložte jej při hlášení problémů pro okamžité třídění.\n\n<details>\n<summary><b>🏗️ 11. „Nasazení a údržba brány je složitá“</b></summary>\n</details>\n\nInstalace, konfigurace a údržba AI proxy v různých prostředích (lokální, VPS, Docker, cloud) je pracná. Problémy, jako jsou pevně zakódované cesty, `EACCES` u adresářů, konflikty portů a multiplatformní sestavení, přispívají k obtížím.\n\n**Jak to OmniRoute řeší:**\n\n- **npm globální instalace** — `npm install -g omniroute && omniroute` — hotovo\n- **Docker Multi-Platform** — AMD64 + nativní ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** — `base` (bez nástrojů CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopová aplikace Electron** — Nativní aplikace pro Windows/macOS/Linux se systémovou lištou, automatickým spuštěním a offline režimem\n- **Režim rozdělených portů** – API a řídicí panel na samostatných portech pro pokročilé scénáře (reverzní proxy, síťování kontejnerů)\n- **Cloud Sync** – Konfigurace synchronizace mezi zařízeními pomocí Cloudflare Workers\n- **Zálohy databází** — Automatické zálohování, obnovení, export a import všech nastavení\n\n<details>\n<summary><b>🌍 12. „Rozhraní je pouze v angličtině a můj tým nemluví anglicky“</b></summary>\n</details>\n\nTýmy v neanglicky mluvících zemích, zejména v Latinské Americe, Asii a Evropě, se potýkají s rozhraními pouze v angličtině. Jazykové bariéry snižují míru přijetí a zvyšují chyby v konfiguraci.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard i18n — 30 jazyků** — Všech 500+ kláves je přeloženo včetně arabštiny, bulharštiny, dánštiny, němčiny, španělštiny, finštiny, francouzštiny, hebrejštiny, hindštiny, maďarštiny, indonéštiny, italštiny, japonštiny, korejštiny, malajštiny, holandštiny, norštiny, polštiny, portugalštiny (PT/BR), rumunštiny, ruštiny, slovenštiny, švédštiny, thajštiny, ukrajinštiny, vietnamštiny, čínštiny, filipínštiny a angličtiny\n- **Podpora RTL** – Podpora psaní zprava doleva pro arabštinu a hebrejštinu\n- **Vícejazyčné soubory README** — 30 kompletních překladů dokumentace\n- **Výběr jazyka** — Ikona glóbu v záhlaví pro přepínání v reálném čase\n\n<details>\n<summary><b>🔄 13. „Potřebuji víc než jen chat – potřebuji vložené soubory, obrázky, zvuk.“</b></summary>\n</details>\n\nUmělá inteligence není jen dokončování chatu. Vývojáři potřebují generovat obrázky, přepisovat zvuk, vytvářet embeddedy pro RAG, měnit pořadí dokumentů a moderovat obsah. Každé API má jiný koncový bod a formát.\n\n**Jak to OmniRoute řeší:**\n\n- **Vkládání** — `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generování obrázků** — `/v1/images/generations` s 10 poskytovateli a více než 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Převod textu na video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Převod textu na hudbu** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Přepis zvuku** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Převod textu na řeč** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a další stávající poskytovatelé\n- **Moderování** — `/v1/moderations` — Kontroly bezpečnosti obsahu\n- **Změna pořadí** — `/v1/rerank` — Změna pořadí relevance dokumentu\n- **Responses API** — Plná podpora `/v1/responses` pro Codex\n\n<details>\n<summary><b>🧪 14. „Nemám způsob, jak testovat a porovnávat kvalitu napříč modely.“</b></summary>\n</details>\n\nVývojáři chtějí vědět, který model je pro jejich případ použití nejlepší – kód, překlad, uvažování – ale ruční porovnávání je pomalé. Neexistují žádné integrované nástroje pro vyhodnocování.\n\n**Jak to OmniRoute řeší:**\n\n- **Hodnocení LLM** — Testování Golden setu s 10 předinstalovanými případy zahrnujícími pozdravy, matematiku, geografii, generování kódu, dodržování JSON, překlad, markdown, odmítnutí bezpečnostních požadavků\n- **4 strategie shody** — `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovací lavice pro překladatelské hřiště** — Dávkové testování s více vstupy a očekávanými výstupy, porovnání napříč poskytovateli\n- **Tester chatu** — Kompletní okružní cesta s vizuálním vykreslováním odpovědí\n- **Živý monitor** — Stream všech požadavků procházejících proxy serverem v reálném čase\n\n<details>\n<summary><b>📈 15. „Potřebuji škálovat bez ztráty výkonu“</b></summary>\n</details>\n\nS rostoucím objemem požadavků generují stejné otázky bez ukládání do mezipaměti duplicitní náklady. Bez idempotence duplicitní požadavky plýtvají zpracováním. Je nutné dodržovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute řeší:**\n\n- **Sémantická mezipaměť** — Dvouvrstvá mezipaměť (signatura + sémantika) snižuje náklady a latenci\n- **Idempotence požadavku** — 5s deduplikační okno pro identické požadavky\n- **Detekce limitu rychlosti** – sledování otáček za minutu (RPM), minimální mezera a maximální souběžné sledování pro každého poskytovatele\n- **Upravitelné limity rychlosti** — Konfigurovatelné výchozí hodnoty v Nastavení → Odolnost s perzistencí\n- **Mezipaměť pro ověření klíčů API** — třívrstvá mezipaměť pro výkon produkčního prostředí\n- **Dashboard s telemetrií** – latence p50/p95/p99, statistiky mezipaměti, dostupnost\n\n<details>\n<summary><b>🤖 16. „Chci mít chování modelů globálně pod kontrolou“</b></summary>\n</details>\n\nVývojáři, kteří chtějí všechny odpovědi v určitém jazyce, se specifickým tónem nebo chtějí omezit tokeny pro uvažování. Konfigurace této funkce v každém nástroji/požadavku je nepraktická.\n\n**Jak to OmniRoute řeší:**\n\n- **Vložení systémového prompt** – Globální prompt aplikovaný na všechny požadavky\n- **Validace rozpočtu Thinking** — Řízení alokace tokenů na požadavek (průchozí, automatické, vlastní, adaptivní)\n- **6 strategií směrování** – Globální strategie, které určují, jak jsou požadavky distribuovány\n- **Směrovač se zástupnými znaky** — vzory `provider/*` dynamicky směrují k libovolnému poskytovateli\n- **Přepínání povolení/zakázání kombinací** – Přepínání kombinací přímo z řídicího panelu\n- **Přepínání poskytovatele** – Povolení/zakázání všech připojení pro poskytovatele jedním kliknutím\n- **Blokovaní poskytovatelé** – Vyloučení konkrétních poskytovatelů ze seznamu `/v1/models`\n\n<details>\n<summary><b>🧰 17. „Potřebuji nástroje MCP jako prvotřídní produktové funkce.“</b></summary>\n</details>\n\nMnoho bran umělé inteligence odhaluje MCP pouze jako skrytý implementační detail. Týmy potřebují viditelnou a spravovatelnou operační vrstvu.\n\n**Jak to OmniRoute řeší:**\n\n- MCP se zobrazuje v navigaci na řídicím panelu a na kartě protokolu koncového bodu.\n- Vyhrazená stránka pro správu MCP s procesy, nástroji, rozsahy a auditem\n- Vestavěný rychlý start pro `omniroute --mcp` a onboarding klienta\n\n<details>\n<summary><b>🧠 18. „Potřebuji orchestraci A2A se synchronizací a cestami úloh streamu.“</b></summary>\n</details>\n\nPracovní postupy agentů vyžadují jak přímé odpovědi, tak dlouhodobé streamované provádění s kontrolou životního cyklu.\n\n**Jak to OmniRoute řeší:**\n\n- Koncový bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamování SSE s šířením stavu terminálu\n- Rozhraní API životního cyklu úloh pro `tasks/get` a `tasks/cancel`\n\n<details>\n<summary><b>🛰️ 19. „Potřebuji skutečný stav procesu MCP, ne odhadovaný stav.“</b></summary>\n</details>\n\nProvozní týmy potřebují vědět, zda je MCP skutečně aktivní, nejen zda je API dosažitelné.\n\n**Jak to OmniRoute řeší:**\n\n- Soubor běhového heartbeatu s PID, časovými razítky, transportem, počtem nástrojů a režimem rozsahu\n- API stavu MCP kombinující prezenční signál a nedávnou aktivitu\n- Karty stavu uživatelského rozhraní pro zobrazení aktuálnosti procesů/provozuschopnosti/prezenčního signálu\n\n<details>\n<summary><b>📋 20. „Potřebuji auditovatelné provedení nástroje MCP“</b></summary>\n</details>\n\nKdyž nástroje mění konfiguraci nebo spouštějí operační akce, týmy potřebují forenzní sledovatelnost.\n\n**Jak to OmniRoute řeší:**\n\n- Protokolování auditu pro volání nástrojů MCP s podporou SQLite\n- Filtruje podle nástroje, úspěchu/neúspěchu, klíče API a stránkování\n- Tabulka auditu dashboardu + koncové body statistik pro automatizaci\n\n<details>\n<summary><b>🔐 21. „Potřebuji omezená oprávnění MCP pro každou integraci.“</b></summary>\n</details>\n\nRůzní klienti by měli mít přístup ke kategoriím nástrojů s nejnižšími oprávněními.\n\n**Jak to OmniRoute řeší:**\n\n- 9 detailních MCP sond pro kontrolovaný přístup k nástrojům\n- Vynucení rozsahu a viditelnost v uživatelském rozhraní správy MCP\n- Bezpečná výchozí poloha pro provozní nástroje\n\n<details>\n<summary><b>⚙️ 22. „Potřebuji provozní kontroly bez nutnosti přesouvání“</b></summary>\n</details>\n\nTýmy potřebují rychlé změny v běhovém prostředí během incidentů nebo nákladových událostí.\n\n**Jak to OmniRoute řeší:**\n\n- Přepněte aktivaci komba přímo z řídicího panelu MCP\n- Používejte profily odolnosti z předdefinovaných balíčků zásad\n- Resetujte stav jističe ze stejného ovládacího panelu\n\n<details>\n<summary><b>🔄 23. „Potřebuji živý přehled o životním cyklu úkolů A2A a jejich zrušení.“</b></summary>\n</details>\n\nBez přehledu o životním cyklu je obtížné třídit incidenty úkolů.\n\n**Jak to OmniRoute řeší:**\n\n- Výpis/filtrování úkolů podle státu/dovednosti s stránkováním\n- Podrobný přehled metadat úloh, událostí a artefaktů\n- Koncový bod zrušení úlohy a akce uživatelského rozhraní s potvrzením\n\n<details>\n<summary><b>🌊 24. „Potřebuji metriky aktivního streamu pro A2A zátěž“</b></summary>\n</details>\n\nStreamovací pracovní postupy vyžadují provozní přehled o souběžnosti a živých připojeních.\n\n**Jak to OmniRoute řeší:**\n\n- Čítače aktivních streamů integrované do stavu A2A\n- Časové razítko posledního úkolu a počty pro jednotlivé stavy\n- Karty A2A dashboardu pro monitorování provozu v reálném čase\n\n<details>\n<summary><b>🪪 25. „Potřebuji standardní vyhledávání agentů pro klienty“</b></summary>\n</details>\n\nExterní klienti a orchestratoři potřebují pro onboarding strojově čitelná metadata.\n\n**Jak to OmniRoute řeší:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazené v uživatelském rozhraní pro správu\n- API pro stav A2A zahrnuje metadata pro zjišťování pro automatizaci\n\n<details>\n<summary><b>🧭 26. „Potřebuji v uživatelském rozhraní produktu zjistitelnost protokolu.“</b></summary>\n</details>\n\nPokud uživatelé nemohou objevit protokolové povrchy, kvalita přijetí a podpory klesá.\n\n**Jak to OmniRoute řeší:**\n\n- Stránka Konsolidované **koncové body** s kartami pro koncové body Proxy, MCP, A2A a API\n- Přepínání stavu inline služby (Online/Offline) pro MCP a A2A\n- Odkazy z přehledu na vyhrazené karty pro správu\n\n<details>\n<summary><b>🧪 27. „Potřebuji komplexní ověření protokolu se skutečnými klienty.“</b></summary>\n</details>\n\nSimulované testy nestačí k ověření kompatibility protokolu před vydáním.\n\n**Jak to OmniRoute řeší:**\n\n- Sada E2E, která spouští aplikaci a používá skutečný transport klienta MCP SDK.\n- Klientské testy A2A pro toky zjišťování, odesílání, streamování, načítání a zrušení\n- Křížová kontrola tvrzení oproti API pro audit MCP a úkoly A2A\n\n<details>\n<summary><b>📡 28. „Potřebuji jednotnou pozorovatelnost napříč všemi rozhraními“</b></summary>\n</details>\n\nRozdělení pozorovatelnosti podle protokolu vytváří slepá místa a delší MTTR.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocené dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie požadavků napříč vrstvami OpenAI, MCP a A2A\n- Provozní API pro stav a automatizaci\n\n<details>\n<summary><b>💼 29. „Potřebuji jeden runtime pro proxy + nástroje + orchestraci agentů“</b></summary>\n</details>\n\nSpouštění mnoha samostatných služeb zvyšuje provozní náklady a počet poruch.\n\n**Jak to OmniRoute řeší:**\n\n- Proxy, MCP server a A2A server kompatibilní s OpenAI v jednom balíčku\n- Sdílené ověřování, odolnost, úložiště dat a pozorovatelnost\n- Konzistentní model politik napříč všemi interakčními plochami\n\n<details>\n<summary><b>🚀 30. „Potřebuji agentské pracovní postupy bez slepení kódu.“</b></summary>\n</details>\n\nTýmy ztrácejí rychlost při spojování více ad-hoc služeb a skriptů.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocená strategie koncových bodů pro klienty a agenty\n- Vestavěná uživatelská rozhraní pro správu protokolů a cesty pro ověřování kouře\n- Základy připravené pro produkční prostředí (zabezpečení, protokolování, odolnost, zálohování)\n\n### Příklady herních plánů (integrované případy užití)\n\n**Příručka A: Maximalizace placeného předplatného + levné zálohování**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Příručka B: Kódovací stack s nulovými náklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Příručka C: Nonstop záložní řetězec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Příručka D: Operace agentů s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Začněte zdarma — Nulové náklady na konfiguraci\n\n> Nastavte si kódování s umělou inteligencí během několika minut za **0 $/měsíc** . Propojte tyto bezplatné účty a využijte vestavěnou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelé odemčeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Připojení **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 – **neomezeně** |\n| 2 | Připojení k **iFlow** (Google OAuth) | kimi-k2-myšlení, qwen3-coder-plus, deepseek-r1... — **neomezeně** |\n| 3 | Připojení **Qwen** (kód zařízení) | qwen3-coder-plus, qwen3-coder-flash... — **neomezeně** |\n| 4 | Připojení **rozhraní příkazového řádku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180 000 GBP/měsíc zdarma** |\n| 5 | `/dashboard/combos` → Šablona **Free Stack (0 $)** | Automatické zařazení všech bezplatných poskytovatelů do routingu |\n\n**V libovolném IDE/CLI naveďte:** `http://localhost:20128/v1` · Klíč API: `any-string` · Hotovo.\n\n> **Volitelné doplňkové krytí (také zdarma):** Groq API klíč (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelů), Cerebras (1 milion tok/den).\n\n## ⚡ Rychlý start\n\n### 1) Nainstalujte a spusťte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uživatelé pnpm:** Po instalaci spusťte `pnpm approve-builds -g` , abyste povolili nativní skripty pro sestavení vyžadované programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard se otevírá na `http://localhost:20128` a základní URL API je `http://localhost:20128/v1` .\n\n| Příkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuštění serveru ( `PORT=20128` , API a dashboard na stejném portu) |\n| `omniroute --port 3000` | Nastavte kanonický/API port na 3000 |\n| `omniroute --mcp` | Spuštění MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevírat prohlížeč automaticky |\n| `omniroute --help` | Zobrazit nápovědu |\n\nVolitelný režim s rozděleným portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Připojte poskytovatele a vytvořte si klíč API\n\n1. Otevřete Dashboard → `Providers` a připojte alespoň jednoho poskytovatele (klíč OAuth nebo API).\n2. Otevřete Dashboard → `Endpoints` a vytvořte API klíč.\n3. (Volitelné) Otevřete Dashboard → `Combos` a nastavte záložní řetězec.\n\n### 3) Nasměrujte svůj kódovací nástroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilními s OpenAI.\n\n### 4) Povolení a ověření protokolů (v2.0)\n\n**MCP (pro operace řízené nástroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak připojte svého MCP klienta přes `stdio` a otestujte nástroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovní postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ověřte vše od začátku do konce (doporučeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ověřuje skutečné toky klientů MCP a A2A v porovnání se spuštěnou aplikací.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## 🐳 Docker\n\nOmniRoute je k dispozici jako veřejný obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlý běh:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostředí:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Používání Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | Štítek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovější stabilní verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuální verze |\n\n---\n\n## 🖥️ Desktopová aplikace – offline a vždy zapnutá\n\n> 🆕 **NOVINKA!** OmniRoute je nyní k dispozici jako **nativní desktopová aplikace** pro Windows, macOS a Linux.\n\nSpusťte OmniRoute jako samostatnou desktopovou aplikaci – pro lokální modely není potřeba žádný terminál, prohlížeč ani internet. Aplikace založená na platformě Electron obsahuje:\n\n- 🖥️ **Nativní okno** — Vyhrazené okno aplikace s integrací do systémové lišty\n- 🔄 **Automatické spuštění** — Spuštění OmniRoute po přihlášení do systému\n- 🔔 **Nativní oznámení** – Získejte upozornění na vyčerpání kvóty nebo problémy s poskytovateli\n- ⚡ **Instalace jedním kliknutím** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline režim** — Funguje plně offline s přiloženým serverem\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systémový zásobník\n\nPo minimalizaci se OmniRoute nachází v systémové liště a nabízí rychlé akce:\n\n- Otevřít řídicí panel\n- Změnit port serveru\n- Ukončit aplikaci\n\n📖 Úplná dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Přehled cen\n\n| Úroveň | Poskytovatel | Náklady | Obnovení kvóty | Nejlepší pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **💳 PŘEDPLATNÉ** | Claude Code (profesionál) | 20 dolarů měsíčně | 5 hodin + týdně | Již přihlášen/a k odběru |\n| Kodex (Plus/Pro) | 20–200 USD/měsíc | 5 hodin + týdně | Uživatelé OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisíc měsíčně + 1 tisíc denně | Každý! |\n| GitHub Copilot | 10–19 USD/měsíc | Měsíční | Uživatelé GitHubu |\n| **🔑 KLÍČ API** | NVIDIA NIM | **ZDARMA** (vývoj navždy) | ~40 ot./min | 70+ otevřených modelů |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší na světě |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisíc otáček za minutu | Ultrarychlá lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | Žádný | Nejlepší zdůvodnění ceny a kvality |\n| xAI Grok-4 Rychlý | **0,20/0,50 USD za 1 milion** 🆕 | Žádný | Nejrychlejší + volání nástroje, ultranízké |\n| xAI Grok-4 (standardní) | 0,20/1,50 USD za 1 milion 🆕 | Žádný | Vlajková loď Reasoning od xAI |\n| Mistral | Zkušební verze zdarma + placené | Omezená sazba | Evropská umělá inteligence |\n| OpenRouter | Platba za použití | Žádný | Více než 100 modelů agregováno. |\n| **💰 LEVNÉ** | GLM-5 (přes Z.AI) 🆕 | 0,5 USD/1 milion | Denně v 10:00 | Výstup 128 tisíc obrazových bodů, nejnovější vlajková loď |\n| GLM-4.7 | 0,6 USD/1 milion | Denně v 10:00 | Záloha rozpočtu |\n| MiniMax M2.5 🆕 | Vstup 0,3 USD/1 milion | 5hodinové válcování | Úvaha + agentní úkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinové válcování | Nejlevnější varianta |\n| Kimi K2.5 (Moonshot API) 🆕 | Platba za použití | Žádný | Přímý přístup k Moonshot API |\n| Kimi K2 | 9 dolarů měsíčně bez závazků | 10 milionů tokenů/měsíc | Předvídatelné náklady |\n| **🆓 ZDARMA** | iFlow | **0 dolarů** | Neomezený | 5 modelů neomezeně |\n| Qwen | **0 dolarů** | Neomezený | 4 modely neomezeně |\n| Kiro | **0 dolarů** | Neomezený | Claude Sonnet/Haiku (tvorce AWS) |\n\n> 🆕 **Přidány nové modely (březen 2026):** řada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkováno na 1143 ms – o 30 % rychlejší než Gemini 2.5 Flash), GLM-5 přes Z.AI s výstupem 128K, uvažování MiniMax M2.5, aktualizované ceny DeepSeek V3.2, Kimi K2.5 přes Moonshot Direct API.\n\n**💡 Kombinovaný balík za 0 $ — Kompletní bezplatná instalace:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\niFlow (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Nulové náklady. Nikdy nepřestávejte s kódováním.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a všechny záložní režimy se provede automaticky – žádné ruční přepínání.\n\n---\n\n---\n\n## 🆓 Bezplatné modely – Co skutečně získáte\n\n> Všechny níže uvedené modely jsou **100% zdarma a nevyžadují žádnou kreditní kartu** . OmniRoute mezi nimi automaticky propojí trasy, když dojde jedna kvóta – zkombinujte je všechny a získejte tak nerozlučnou kombinaci za 0 dolarů.\n\n### 🔵 CLAUDE MODELS (přes Kiro — AWS Builder ID)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-opus-4.6` | `kr/` | **Neomezený** | Nejnovější opus od Kira |\n\n### 🟢 MODELY IFLOW (Bezplatné OAuth — bez nutnosti platit kreditní kartou)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-plus` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `deepseek-r1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `minimax-m2.1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `kimi-k2` | `if/` | **Neomezený** | Žádný hlášený strop |\n\n### 🟡 MODELY QWEN (Ověření kódu zařízení)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-next` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `vision-model` | `qw/` | **Neomezený** | Multimodální (obrázky) |\n\n### 🟣 Rozhraní GEMINI CLI (Google OAuth)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisíc tok/měsíc** + 1 tisíc/den | Měsíční reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisíc měsíčně (sdílený bazén) | Vysoká kvalita |\n\n### ⚫ NVIDIA NIM (Bezplatný klíč API — build.nvidia.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vývojář) | Žádný limit tokenů | **~40 ot./min** | Více než 70 modelů; přechod na čisté limity sazeb v polovině roku 2025 |\n\nOblíbené bezplatné modely: `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`\n\n### ⚪ CEREBRAS (Bezplatný klíč API — inference.cerebras.ai)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenů/den** | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší inference LLM na světě; denně se resetuje |\n\nDostupné zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Bezplatný API klíč — console.groq.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisíc otáček za minutu** | 30 ot./min na model | Žádná kreditní karta; limit 429, neúčtováno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **💡 Ultimátní bezplatný zásobník:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> → iFlow (5 models, unlimited)\n> → Qwen (4 models, unlimited)\n> → Gemini CLI (180K/mo)\n> → Cerebras (1M tok/day)\n> → Groq (14.4K req/day)\n> → NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a už nikdy nebudete platit za umělou inteligenci.\n\n## 🎙️ Kombinovaná transkripce zdarma\n\n> Přepisujte libovolné audio/video za **0 $** – Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako záložní nástroj, Groq Whisper jako neomezená nouzová záloha.\n\n| Poskytovatel | Bezplatné kredity | Nejlepší model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| 🟢 **Deepgram** | **200 dolarů zdarma** (registrace) | `nova-3` — nejvyšší přesnost, více než 30 jazyků | Žádný limit RPM pro kredity zdarma |\n| 🔵 **AssemblyAI** | **50 dolarů zdarma** (registrace) | `universal-3-pro` — kapitoly, sentiment, osobní údaje | Žádný limit RPM pro kredity zdarma |\n| 🔴 **Groq** | **Navždy zdarma** | `whisper-large-v3` — OpenAI Šepot | 30 ot./min (omezená rychlost) |\n\n**Navrhovaná kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nPak v `/dashboard/media` → záložka **Přepis** : nahrajte libovolný zvukový nebo video soubor → vyberte kombinovaný koncový bod → získejte přepis v podporovaných formátech.\n\n## 💡 Klíčové vlastnosti\n\nOmniRoute v2.0 je navržen jako operační platforma, nikoli pouze jako proxy pro relé.\n\n### 🆕 Nové — Vylepšení inspirovaná ClawRouterem (březen 2026)\n\n| Funkce | Co to dělá |\n| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Rychlá rodina** | Modely xAI za 0,20 USD/0,50 USD/M – v benchmarku 1143 ms (o 30 % rychlejší než Gemini 2.5 Flash) |\n| 🧠 **GLM-5 přes Z.AI** | 128 tisíc výstupních dat, 0,5 USD/1 milion USD – nejnovější vlajková loď rodiny GLM |\n| 🔮 **MiniMax M2.5** | Úvaha + agentní úkoly za 0,30 USD/1 milion – významný upgrade oproti M2.1 |\n| 🎯 **Příznak volání nástroje pro každý model** | `toolCalling: true/false` v registru — AutoCombo přeskakuje modely, které nepodporují nástroje. |\n| 🌍 **Detekce vícejazyčného záměru** | Klíčová slova PT/ZH/ES/AR v bodování AutoCombo – lepší výběr modelu pro neanglický obsah |\n| 📊 **Záložní metody řízené benchmarkem** | Skutečná latence p95 z živých požadavků poskytuje kombinované skóre – AutoCombo se učí ze skutečných dat |\n| 🔁 **Požádat o deduplikaci** | Okno pro deduplikaci na základě hashování obsahu – bezpečné pro více agentů, zabraňuje duplicitním platbám |\n| 🔌 **Strategie pro zásuvné routery** | Rozšiřitelné rozhraní `RouterStrategy` – přidejte si vlastní logiku směrování jako pluginy |\n\n### 🚀 Předchozí verze v2.0.9+ — Hřiště, otisky prstů v CLI a ACP\n\n| Funkce | Co to dělá |\n| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Modelové hřiště** | Stránka řídicího panelu pro přímé testování libovolného modelu – selektory poskytovatele/modelu/koncového bodu, editor Monaco, streamování, přerušení, načasování |\n| 🔏 **Porovnávání otisků prstů v CLI** | Řazení hlaviček/těl serveru podle poskytovatele tak, aby odpovídalo nativním podpisům CLI – přepínání pro jednotlivé poskytovatele v Nastavení &gt; Zabezpečení. **Vaše IP adresa proxy serveru je zachována.** |\n| 🤝 **Podpora ACP (Agent Client Protocol)** | Vyhledávání agentů CLI (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 dalších), generátor procesů, koncový bod `/api/acp/agents` |\n| 🤖 **Řídicí panel agentů ACP** | Ladění › Stránka Agenti — mřížka 14 agentů se stavem instalace, verzí a formulářem pro vlastní agenta pro libovolný nástroj CLI. Uživatelé **OpenCode** získají tlačítko „Stáhnout opencode.json“, které automaticky vygeneruje konfiguraci připravenou k použití se všemi dostupnými modely. |\n| 🔧 **Směrování `apiFormat` pro vlastní model** | Vlastní modely s `apiFormat: \"responses\"` nyní správně směrují do překladače Responses API. |\n| 🏢 **Izolace pracovního prostoru Codexu** | Více pracovních prostorů Codexu na jeden e-mail – OAuth správně odděluje připojení podle ID pracovního prostoru |\n| 🔄 **Automatická aktualizace elektronů** | Desktopová aplikace kontroluje aktualizace + automaticky se instaluje po restartu |\n\n### 🤖 Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dělá |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **MCP Server (16 nástrojů)** | Nástroje IDE/agent prostřednictvím 3 transportů: stdio, SSE ( `/api/mcp/sse` ), Streamovatelný HTTP ( `/api/mcp/stream` ) |\n| 🤝 **A2A server (JSON-RPC + SSE)** | Spouštění úloh mezi agenty se synchronizací a streamováním |\n| 🧭 **Konsolidovaná stránka koncových bodů** | Stránka pro správu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| 🎚️ **Přepínače pro povolení/zakázání služby** | Přepínače ZAP/VYP pro MCP a A2A s trvalým nastavením (výchozí: VYP) |\n| 🛰️ **Srdeční tep za běhu MCP** | Skutečný stav procesu (pid, doba provozuschopnosti, stáří heartbeatu, transport, režim rozsahu) |\n| 📋 **Auditní záznam MCP** | Filtrovatelné protokoly auditu s hodnocením úspěchu/neúspěchu a klíčovým přiřazením |\n| 🔐 **Vynucování rozsahu MCP** | 9 podrobných oprávnění pro řízený přístup k nástrojům |\n| 📡 **Správa životního cyklu úkolů A2A** | Seznam/filtrování úloh, kontrola událostí/artefaktů, zrušení spuštěných úloh |\n| 📋 **Objevení karty agenta** | `/.well-known/agent.json` pro automatické vyhledávání klientů |\n| 🧪 **Testovací postroj Protocol E2E** | Skutečné MCP SDK + toky klientů A2A v `test:protocols:e2e` |\n| ⚙️ **Provozní kontroly** | Kombinace přepínačů, použití profilů odolnosti, resetování jističů z jednoho ovládacího panelu |\n\n### 🧠 Směrování a inteligence\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| 🎯 **Inteligentní čtyřúrovňový záložní systém** | Automatická trasa: Předplatné → API klíč → Levné → Zdarma |\n| 📊 **Sledování kvót v reálném čase** | Počet tokenů v reálném čase + odpočet resetování pro každého poskytovatele |\n| 🔄 **Překlad formátu** | OpenAI ↔ Claude ↔ Gemini ↔ Odpovědi s konverzemi bezpečnými pro schéma |\n| 👥 **Podpora více účtů** | Více účtů na poskytovatele s inteligentním výběrem |\n| 🔄 **Automatická aktualizace tokenů** | Tokeny OAuth se automaticky obnovují při opakovaném pokusu. |\n| 🎨 **Vlastní kombinace** | 6 vyvažovacích strategií + řízení záložního řetězce |\n| 🌐 **Směrovač se zástupnými znaky** | dynamické směrování `provider/*` |\n| 🧠 **Přemýšlení o rozpočtových kontrolách** | Limity pro průchozí, automatické, vlastní a adaptivní uvažování |\n| 🔀 **Aliasy modelů** | Vestavěné + vlastní aliasování modelů a bezpečnost migrace |\n| ⚡ **Degradace pozadí** | Směrujte úlohy na pozadí s nízkou prioritou na levnější modely |\n| 🧪 **Chytré směrování s ohledem na úkoly** | Automatický výběr modelu podle typu obsahu (kódování/vize/analýza/sumarizace) |\n| 💬 **Vstřikování do systému** | Globální kontroly chování uplatňované konzistentně |\n| 📄 **Kompatibilita API pro odpovědi** | Plná podpora `/v1/responses` pro Codex a pokročilé agentické pracovní postupy |\n\n### 🎵 Multimodální API\n\n| Funkce | Co to dělá |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Generování obrázků** | `/v1/images/generations` s cloudovým a lokálním backendem |\n| 📐 **Vložení** | `/v1/embeddings` pro vyhledávání a RAG pipelines |\n| 🎤 **Přepis zvuku** | `/v1/audio/transcriptions` (Whisper a další poskytovatelé) |\n| 🔊 **Převod textu na řeč** | `/v1/audio/speech` (více enginů/poskytovatelů) |\n| 🎬 **Generování videa** | `/v1/videos/generations` (pracovní postupy ComfyUI + SD WebUI) |\n| 🎵 **Hudební generace** | `/v1/music/generations` (pracovní postupy ComfyUI) |\n| 🛡️ **Moderování** | Bezpečnostní kontroly `/v1/moderations` |\n| 🔀 **Změna pořadí** | `/v1/rerank` pro hodnocení relevance |\n| 🔍 **Vyhledávání na webu** 🆕 | `/v1/search` — 5 poskytovatelů (Serper, Brave, Perplexity, Exa, Tavily), více než 6 500 zdarma/měsíc, automatické přepnutí na záložní systém, mezipaměť |\n\n### 🛡️ Odolnost, bezpečnost a správa věcí veřejných\n\n| Funkce | Co to dělá |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| 🔌 **Jističe** | Vypnutí/obnovení pro každý model s ovládáním prahových hodnot |\n| 🎯 **Modely s ohledem na koncové body** | Vlastní modely deklarují podporované koncové body + formát API |\n| 🛡️ **Stádo proti hromům** | Ochrana mutexu a semaforu při událostech opakování/rychlosti |\n| 🧠 **Sémantická + podpisová mezipaměť** | Snížení nákladů/latence díky dvěma vrstvám mezipaměti |\n| ⚡ **Žádost o idempotenci** | Okno ochrany proti duplikacím |\n| 🔒 **Falšování otisků prstů pomocí TLS** | Otisk TLS podobný prohlížeči – **snižuje detekci botů a nahlašování účtů** |\n| 🔏 **Porovnávání otisků prstů v CLI** | Shoduje se s nativními podpisy požadavků CLI – **snižuje riziko zablokování a zároveň zachovává IP adresu proxy** |\n| 🌐 **Filtrování IP adres** | Ovládání seznamu povolených/blokovaných položek pro odhalená nasazení |\n| 📊 **Upravitelné limity rychlosti** | Konfigurovatelné globální/na úrovni poskytovatele limity s perzistencí |\n| 🔑 **Správa klíčů API a stanovení rozsahu** | Bezpečné vydávání/rotace klíčů a kontroly modelu/poskytovatele |\n| 🛡️ **Chráněné `/models`** | Volitelné ověřování a skrytí poskytovatele pro katalog modelů |\n\n### 📊 Pozorovatelnost a analytika\n\n| Funkce | Co to dělá |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| 📝 **Žádost + protokolování proxy** | Úplné protokolování požadavků/odpovědí a proxy |\n| 📋 **Sjednocený panel protokolů** | Zobrazení požadavků, proxy, auditu a konzole na jedné stránce |\n| 🔍 **Vyžádat si telemetrii** | Latence p50/p95/p99 a trasování požadavků |\n| 🏥 **Panel zdraví** | Doba provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti |\n| 💰 **Sledování nákladů** | Kontrola rozpočtu a přehled o cenách pro jednotlivé modely |\n| 📈 **Analytické vizualizace** | Přehledy využití modelů/poskytovatelů a zobrazení trendů |\n| 🧪 **Rámec hodnocení** | Testování zlaté sady s konfigurovatelnými strategiemi shody |\n\n### ☁️ Nasazení a platforma\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| 🌐 **Nasazení kdekoli** | Localhost, VPS, Docker, cloudová prostředí |\n| 💾 **Synchronizace s cloudem** | Synchronizace konfigurace přes cloud worker |\n| 🔄 **Zálohování/Obnovení** | Toky exportu/importu a obnovy po havárii |\n| 🧙 **Průvodce nástupem** | Průvodce prvním spuštěním |\n| 🔧 **Panel nástrojů CLI** | Nastavení oblíbených kódovacích nástrojů jedním kliknutím |\n| 🎮 **Modelové hřiště** | Otestujte libovolného poskytovatele/model/koncový bod z řídicího panelu |\n| 🔏 **Přepínač otisků prstů v příkazovém řádku** | Porovnávání otisků prstů podle poskytovatele v Nastavení &gt; Zabezpečení |\n| 🌐 **i18n (30 jazyků)** | Plná jazyková podpora dashboardu a dokumentace s psaním zprava doleva |\n| 📂 **Adresář vlastních dat** | Přepsání `DATA_DIR` pro umístění úložiště |\n\n### Hluboký pohled na funkce\n\n#### Chytrá záložní funkce s praktickou kontrolou nákladů\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyž selže kvóta, rychlost nebo stav, OmniRoute automaticky přejde k dalšímu kandidátovi bez nutnosti ručního přepínání.\n\n#### Správa protokolů, která je viditelná a ovladatelná\n\n- MCP + A2A jsou viditelné v uživatelském rozhraní a dokumentaci (nejsou skryté)\n- API pro stav protokolu zpřístupňují živá provozní data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnují akce pro operace 2. dne (přepínání kombinací, resetování jističů, zrušení úkolů)\n\n#### Pracovní postup překladatele + validace\n\nOblast překladatele zahrnuje:\n\n- **Hřiště** : kontroly transformace požadavků\n- **Tester chatu** : kompletní okružní cesta požadavku/odpovědi\n- **Testovací stolice** : více případů v jednom běhu\n- **Živý monitor** : zobrazení provozu v reálném čase\n\nPlus validace protokolu se skutečnými klienty pomocí `npm run test:protocols:e2e` .\n\n> 📖 **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** — Referenční informace o nástrojích, konfigurace IDE a příklady klientů\n>\n> 📖 **[Soubor README pro A2A Server](src/lib/a2a/README.md)** — Dovednosti, metody JSON-RPC, streamování a životní cyklus úloh\n\n## 🧪 Hodnocení (Evals)\n\nOmniRoute obsahuje vestavěný hodnotící rámec pro testování kvality odpovědí LLM v porovnání se zlatou sadou. Přístup k němu je možný přes **Analýzy → Hodnocení** v dashboardu.\n\n### Vestavěná zlatá sada\n\nPředinstalovaná sada „OmniRoute Golden Set“ obsahuje testovací případy pro:\n\n- Zdravím, matematika, zeměpis, generování kódu\n- Shoda s formátem JSON, překlad, generování markdownů\n- Bezpečnostní odmítnutí (škodlivý obsah), počítání, booleovská logika\n\n### Strategie hodnocení\n\n| Strategie | Popis | Příklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Výstup se musí přesně shodovat | `\"4\"` |\n| `contains` | Výstup musí obsahovat podřetězec (bez rozlišení velkých a malých písmen) | `\"Paris\"` |\n| `regex` | Výstup musí odpovídat vzoru regulárních výrazů | `\"1.*2.*3\"` |\n| `custom` | Vlastní JS funkce vrací true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Průvodce nastavením\n\n### Nastavení protokolu (MCP + A2A)\n\n<details>\n<summary><b>🧩 Nastavení MCP (Model Context Protocol)</b></summary>\n</details>\n\nSpuštění MCP transportu v režimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporučený postup ověření:\n\n1. Připojte svého MCP klienta přes stdio.\n2. Spusťte `omniroute_get_health` .\n3. Spusťte `omniroute_list_combos` .\n4. Otevřete `/dashboard/mcp` pro ověření prezenčního signálu, aktivity a auditu.\n\nUžitečná API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n<details>\n<summary><b>🤝 Nastavení A2A (Agent2Agent)</b></summary>\n</details>\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat úkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSpráva životního cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvozní uživatelské rozhraní:\n\n- `/dashboard/a2a` pro pozorovatelnost úloh/stavů/streamů a akce kouření\n\n<details>\n<summary><b>🧪 Komplexní validace protokolu</b></summary>\n</details>\n\nOvěřte oba protokoly se skutečnými klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTím se ověřuje:\n\n- Připojení/seznam/volání klienta MCP SDK\n- A2A objevování/odesílání/streamování/získávání/zrušení\n- Křížová kontrola dat v auditu MCP a API pro správu úloh A2A\n\n<details>\n<summary><b>💳 Poskytovatelé předplatného</b></summary>\n</details>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionály:** Pro složité úkoly používejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvótu pro každý model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Správa limitů účtu Codex (5h + týdně)\n\nKaždý účet Codex má nyní přepínače zásad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinového prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zásadu týdenního prahu okna.\n- Prahové chování: když povolené okno dosáhne využití &gt;=90 %, je daný účet přeskočen.\n- Chování rotace: OmniRoute automaticky přesměruje na další způsobilý účet Codex.\n- Chování při resetování: Po `resetAt` určité doby se účet automaticky opět stane způsobilým.\n\nScénáře:\n\n- `5h ON` + `Weekly ON` : účet je přeskočen, když kterékoli z oken dosáhne prahové hodnoty.\n- `5h OFF` + `Weekly ON` : účet může být zablokován pouze týdenním používáním.\n- `5h ON` + `Weekly OFF` : účet může být zablokován pouze při 5hodinovém používání.\n- `resetAt` passed: účet se automaticky znovu zapne (bez ručního opětovného povolení).\n\n### Gemini CLI (ZDARMA 180 000/měsíc!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepší hodnota:** Obrovská bezplatná úroveň! Použijte ji před placenými úrovněmi.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n<details>\n<summary><b>🔑 Poskytovatelé klíčů API</b></summary>\n</details>\n\n### NVIDIA NIM (BEZPLATNÝ přístup pro vývojáře — více než 70 modelů)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Získejte zdarma klíč API (včetně 1000 inferenčních kreditů)\n3. Ovládací panel → Přidat poskytovatele → NVIDIA NIM:\n - Klíč API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a více než 50 dalších\n\n**Tip pro profesionály:** API kompatibilní s OpenAI – funguje bez problémů s překladem formátů OmniRoute!\n\n### Hluboké vyhledávání\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatná úroveň!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Získejte klíč API (včetně bezplatné úrovně)\n3. Ovládací panel → Přidat poskytovatele → Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionály:** Ultrarychlá inference – nejlepší pro kódování v reálném čase!\n\n### OpenRouter (100+ modelů)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → OpenRouter\n\n**Modely:** Získejte přístup k více než 100 modelům od všech hlavních poskytovatelů prostřednictvím jediného klíče API.\n\n<details>\n<summary><b>💰 Levní poskytovatelé (záložní)</b></summary>\n</details>\n\n### GLM-4.7 (Denní reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Získejte klíč API z kódovacího plánu\n3. Nástěnka → Přidat klíč API:\n - Poskytovatel: `glm`\n - Klíč API: `your-key`\n\n**Použití:** `glm/glm-4.7`\n\n**Tip pro profesionály:** Programovací plán nabízí 3× kvótu za cenu 1/7! Obnovuje se denně v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionály:** Nejlevnější varianta pro dlouhý kontext (1 milion tokenů)!\n\n### Kimi K2 (paušální poplatek 9 dolarů měsíčně)\n\n1. Odebírat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `kimi/kimi-latest`\n\n**Tip pro profesionály:** Fixních 9 $/měsíc za 10 milionů tokenů = efektivní náklady 0,90 $/1 milion!\n\n<details>\n<summary><b>🆓 BEZPLATNÍ poskytovatelé (nouzové zálohování)</b></summary>\n</details>\n\n### iFlow (5 BEZPLATNÝCH modelů přes OAuth)\n\n```bash\nDashboard → Connect iFlow\n→ iFlow OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kódem zařízení)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n<details>\n<summary><b>🎨 Vytvořte kombinace</b></summary>\n</details>\n\n### Příklad 1: Maximalizace předplatného → Levné zálohování\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Příklad 2: Pouze zdarma (nulové náklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n<details>\n<summary><b>🔧 Integrace s rozhraním příkazového řádku</b></summary>\n</details>\n\n### IDE kurzoru\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jedním kliknutím použijte stránku **Nástroje CLI** na řídicím panelu nebo ručně upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Možnost 1 – Dashboard (doporučeno):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Možnost 2 – Manuální úprava:** Úprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznámka:** OpenClaw funguje pouze s lokálním OmniRoute. Místo `localhost` použijte `127.0.0.1` , abyste se vyhnuli problémům s rozlišením IPv6.\n\n### Cline / Pokračovat / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Přidání OmniRoute jako vlastního poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvořte/upravte `opencode.json` v kořenovém adresáři projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` přidejte jakýkoli model dostupný ve vašem koncovém bodu OmniRoute `/v1/models` . Použijte formát `provider/model-id` z vašeho dashboardu OmniRoute.\n\n---\n\n## 🐛 Řešení problémů\n\n<details>\n<summary><b>Kliknutím rozbalíte průvodce řešením problémů</b></summary>\n</details>\n\n**\"Jazykový model neposkytoval zprávy\"**\n\n- Kvóta poskytovatele vyčerpána → Zkontrolujte sledování kvót na řídicím panelu\n- Řešení: Použijte záložní kombinovanou variantu nebo přejděte na levnější úroveň\n\n**Omezení rychlosti**\n\n- Kvóta předplatného vyčerpána → Přechod na GLM/MiniMax\n- Přidat kombo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vypršela**\n\n- Automaticky aktualizováno službou OmniRoute\n- Pokud problémy přetrvávají: Ovládací panel → Poskytovatel → Znovu připojit\n\n**Vysoké náklady**\n\n- Zkontrolujte statistiky využití v sekci Nástěnka → Náklady\n- Přepnout primární model na GLM/MiniMax\n- Pro nekritické úlohy použijte bezplatnou úroveň (Gemini CLI, iFlow).\n\n**Porty řídicího panelu/API jsou nesprávné**\n\n- `PORT` je kanonický základní port (a standardně port API)\n- `API_PORT` přepisuje pouze posluchač API kompatibilní s OpenAI.\n- `DASHBOARD_PORT` přepisuje pouze posluchač dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaši veřejnou URL adresu řídicího panelu (pro zpětná volání OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ověřte, zda `BASE_URL` odkazuje na vaši spuštěnou instanci.\n- Ověřte, zda `CLOUD_URL` odkazuje na váš očekávaný cloudový koncový bod.\n- Udržujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na straně serveru.\n\n**První přihlášení nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud není nastaveno, záložní heslo je `123456`\n\n**Žádné protokoly požadavků**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test připojení ukazuje „Neplatné“ pro poskytovatele kompatibilní s OpenAI**\n\n- Mnoho poskytovatelů nezpřístupňuje koncový bod `/models`\n- OmniRoute v1.0.6+ zahrnuje záložní ověření pomocí dokončení chatu\n- Zajistěte, aby základní URL adresa obsahovala příponu `/v1`\n\n### 🔐 OAuth na vzdáleném serveru\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Důležité pro uživatele, kteří provozují OmniRoute na VPS, Dockeru nebo jakémkoli vzdáleném serveru**\n\n#### Proč selhává OAuth v rozhraní CLI Antigravity / Gemini na vzdálených serverech?\n\nPoskytovatelé rozhraní CLI **Antigravity** a **Gemini** používají **Google OAuth 2.0** . Google vyžaduje, aby se `redirect_uri` v toku OAuth přesně shodoval s jedním z předregistrovaných URI v konzoli Google Cloud Console aplikace.\n\nPřihlašovací údaje OAuth, které jsou součástí OmniRoute, jsou registrovány **pouze pro `localhost`** . Když přistupujete k OmniRoute na vzdáleném serveru (např. `https://omniroute.myserver.com` ), Google odmítne ověření pomocí:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Řešení: Nakonfigurujte si vlastní přihlašovací údaje OAuth\n\nV Google Cloud Console je potřeba vytvořit **ID klienta OAuth 2.0** s URI vašeho serveru.\n\n#### Krok za krokem\n\n**1. Otevřete konzoli Google Cloud**\n\nPřejděte na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvořte nové ID klienta OAuth 2.0**\n\n- Klikněte na **„+ Vytvořit přihlašovací údaje“** → **„ID klienta OAuth“**\n- Typ aplikace: **„Webová aplikace“**\n- Název: cokoli chcete (např. `OmniRoute Remote` )\n\n**3. Přidejte autorizované URI pro přesměrování**\n\nDo pole **„Autorizované identifikátory URI pro přesměrování“** přidejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraďte `your-server.com` doménou nebo IP adresou vašeho serveru (v případě potřeby uveďte i port, např. `http://45.33.32.156:20128/callback` ).\n\n**4. Uložte a zkopírujte přihlašovací údaje**\n\nPo vytvoření Google zobrazí **ID klienta** a **tajný kód klienta** .\n\n**5. Nastavení proměnných prostředí**\n\nVe vašem souboru `.env` (nebo proměnných prostředí Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu připojit**\n\nŘídicí panel → Poskytovatelé → Antigravity (nebo Gemini CLI) → OAuth\n\nGoogle nyní bude správně přesměrovávat na `https://your-server.com/callback` .\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nPokud si teď nechcete nastavovat vlastní přihlašovací údaje, můžete stále použít **ruční postup pro URL** :\n\n1. OmniRoute otevírá autorizační URL od Googlu\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru).\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče (i když se stránka nenačte)\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute.\n5. Klikněte na **„Připojit“**\n\n> To funguje, protože autorizační kód v URL adrese je platný bez ohledu na to, zda se načetla přesměrovací stránka.\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nChcete-li získat přístup k přihlašovacím údajům bez vlastní konfigurace, můžete použít následující postup:\n\n1. OmniRoute otevře URL autorizace Google\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru)\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute\n5. Klikněte na **„Připojit\"**\n\n> Toto řešení funguje, protože autorizační kód v URL adrese je platný bez ohledu na načtení přesměrovací stránky.\n\n---\n\n## 🛠️ Technologický stack\n\n<details>\n<summary><b>Kliknutím rozbalíte podrobnosti o technologickém stacku</b></summary>\n</details>\n\n- **Runtime** : Node.js 18–22 LTS (⚠️ Node.js 24+ **není podporován** — nativní binární soubory `better-sqlite3` jsou nekompatibilní)\n- **Jazyk** : TypeScript 5.9 — **100% TypeScript** napříč `src/` a `open-sse/` ( `any` v základních modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databáze** : LowDB (JSON) + SQLite (stav domény + protokoly proxy + audit MCP + rozhodnutí o směrování)\n- **Schémata** : Zod (validace I/O nástrojů MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamování** : Události odeslané serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klíče + autorizace s rozsahem MCP\n- **Testování** : Node.js test runner + Vitest (900+ testů včetně unit, integračních, E2E)\n- **CI/CD** : Akce GitHubu (automatické publikování v npm + Docker Hub při vydání)\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **Balíček** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistič, exponenciální odstavení, ochrana proti hromům, falešné TLS, automatické kombinované samoopravování\n\n---\n\n## 📖 Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uživatelská příručka](docs/USER_GUIDE.md) | Poskytovatelé, kombinace, integrace CLI, nasazení |\n| [Referenční informace k API](docs/API_REFERENCE.md) | Všechny koncové body s příklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nástrojů MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamování, správa úloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorové bodování, balíčky režimů, samoléčba |\n| [Odstraňování problémů](docs/TROUBLESHOOTING.md) | Běžné problémy a jejich řešení |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a interní prvky systému |\n| [Přispívání](CONTRIBUTING.md) | Nastavení a pokyny pro vývoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpečnostní zásady](SECURITY.md) | Hlášení zranitelností a bezpečnostní postupy |\n| [Nasazení virtuálního počítače](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletní průvodce: Nastavení virtuálního počítače + nginx + Cloudflare |\n| [Galerie funkcí](docs/FEATURES.md) | Vizuální prohlídka řídicího panelu se snímky obrazovky |\n| [Kontrolní seznam vydání](docs/RELEASE_CHECKLIST.md) | Kroky ověření před vydáním |\n\n---\n\n## 🗺️ Plán\n\nOmniRoute má **v plánu více než 210 funkcí** v několika fázích vývoje. Zde jsou klíčové oblasti:\n\n| Kategorie | Plánované funkce | Hlavní body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| 🧠 **Směrování a inteligence** | 25+ | Směrování s nejnižší latencí, směrování založené na tagech, kontrola kvót před výstupem, výběr účtu P2C |\n| 🔒 **Zabezpečení a dodržování předpisů** | 20+ | Zpevnění SSRF, maskování přihlašovacích údajů, limit rychlosti pro každý koncový bod, stanovení rozsahu klíčů pro správu |\n| 📊 **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledování kvót v reálném čase, sledování nákladů podle modelu |\n| 🔄 **Integrace poskytovatelů** | 20+ | Dynamický registr modelů, doba zchlazení poskytovatelů, Codex pro více účtů, analýza kvót Copilota |\n| ⚡ **Výkon** | 15+ | Dvojitá vrstva mezipaměti, mezipaměť výzev, mezipaměť odpovědí, udržování streamování, dávkové API |\n| 🌐 **Ekosystém** | 10+ | WebSocket API, horké opětovné načítání konfigurace, distribuované úložiště konfigurace, komerční režim |\n\n### 🔜 Již brzy\n\n- 🔗 **Integrace OpenCode** — Nativní podpora poskytovatelů pro IDE kódování s AI v OpenCode\n- 🔗 **Integrace TRAE** — Plná podpora vývojového rámce TRAE pro umělou inteligenci\n- 📦 **Dávkové API** — Asynchronní dávkové zpracování hromadných požadavků\n- 🎯 **Směrování na základě tagů** — Směrování požadavků na základě vlastních tagů a metadat\n- 💰 **Strategie nejnižších nákladů** – Automaticky vybere nejlevnějšího dostupného poskytovatele\n\n> 📝 Úplné specifikace funkcí jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobných specifikací)\n\n---\n\n## 👥 Přispěvatelé\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Přispěvatelé](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak přispět\n\n1. Vytvoření forku repozitáře\n2. Vytvořte si vlastní větev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrďte změny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do větve ( `git push origin feature/amazing-feature` )\n5. Otevřít žádost o změny (pull request)\n\nPodrobné pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydání nové verze\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Hvězdná historie\n\n## Hvězdáři v průběhu času\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvězdáři v průběhu času](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## 🙏 Poděkování\n\nZvláštní poděkování patří **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** – původnímu projektu, který inspiroval tento fork. OmniRoute staví na tomto neuvěřitelném základu s dalšími funkcemi, multimodálními API a kompletním přepsáním TypeScriptu.\n\nZvláštní poděkování patří **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – původní implementaci Go, která inspirovala tento JavaScriptový port.\n\n---\n\n## 📄 Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n<div align=\"center\">\n <sub>Vytvořeno s ❤️ pro vývojáře, kteří programují 24 hodin denně, 7 dní v týdnu</sub>\n <br>\n <sub><p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\">omniroute.online</a></p></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}, "5d82ffa5035fe613056f43fb25172a0126d21323": {"t": 1785764471.6996114, "n": 94606, "h": "63d505373ea22e39", "c": "# 🚀 OmniRoute — Bezplatná brána umělé inteligence\n\n### Nikdy nepřestávejte s kódováním. Chytré směrování k **BEZPLATNÝM a levným modelům AI** s automatickým přepínáním mezi záložními systémy.\n\n_Váš univerzální API proxy – jeden endpoint, více než 44 poskytovatelů, nulové výpadky. Nyní s orchestrací agentů **MCP a A2A** ._\n\n**Dokončení chatu • Vkládání • Generování obrázků • Video • Hudba • Audio • Změna pořadí • **Vyhledávání na webu** • MCP server • A2A protokol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n</div>\n<p data-md-type=\"paragraph\"><a href=\"https://www.npmjs.com/package/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/npm/v/omniroute?color=cb3837&amp;logo=npm\" alt=\"verze npm\" data-md-type=\"image\"><a href=\"https://hub.docker.com/r/diegosouzapw/omniroute\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&amp;logo=docker&amp;color=2496ED\" alt=\"Docker Hub\" data-md-type=\"image\"><a href=\"https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/github/license/diegosouzapw/OmniRoute\" alt=\"Licence\" data-md-type=\"image\"><a href=\"https://omniroute.online\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&amp;logoColor=white\" alt=\"Webové stránky\" data-md-type=\"image\"><a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\"></a><img src=\"https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&amp;logoColor=white\" alt=\"WhatsApp\" data-md-type=\"image\"></p>\n<p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\" data-md-type=\"link\">🌐 Webové stránky</a> • <a href=\"#-quick-start\" data-md-type=\"link\">🚀 Rychlý start</a> • <a href=\"#-key-features\" data-md-type=\"link\">💡 Funkce</a> • <a href=\"#-documentation\" data-md-type=\"link\">📖 Dokumentace</a> • <a href=\"#-pricing-at-a-glance\" data-md-type=\"link\">💰 Ceník</a> • <a href=\"https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t\" data-md-type=\"link\">💬 WhatsApp</a></p>\n<div data-md-type=\"block_html\"></div>\n\n🌐 **Dostupné v:** 🇺🇸 [Angličtina](README.md) | 🇧🇷 [Português (Brazílie)](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) | 🇩🇰 [Dánsko](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [maďarština](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonésie](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nizozemsko](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugalsko)](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) | 🇵🇭 [Filipínec](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)\n\n---\n\n## 🖼️ Hlavní ovládací panel\n\n<div align=\"center\"> <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"Řídicí panel OmniRoute\" width=\"800\"> </div>\n\n---\n\n## 📸 Náhled řídicího panelu\n\n<details>\n<summary><b>Kliknutím zobrazíte snímky obrazovky z řídicího panelu</b></summary>\n</details>\n\n| Strana | Snímek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelé** | ![Poskytovatelé](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdraví** | ![Zdraví](docs/screenshots/04-health.png) |\n| **Překladatel** | ![Překladatel](docs/screenshots/05-translator.png) |\n| **Nastavení** | ![Nastavení](docs/screenshots/06-settings.png) |\n| **Nástroje CLI** | ![Nástroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly používání** | ![Používání](docs/screenshots/08-usage.png) |\n| **Koncové body** | ![Koncové body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### 🤖 Bezplatný poskytovatel umělé inteligence pro vaše oblíbené programátory\n\n_Připojte libovolný nástroj IDE nebo CLI s umělou inteligencí přes OmniRoute — bezplatnou API bránu pro neomezené kódování._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openclaw/openclaw\"><img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"><br><b>OpenClaw</b></a><br> <sub>⭐ 205 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/HKUDS/nanobot\"><img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"><br><b>NanoBot</b></a><br> <sub>⭐ 20,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/sipeed/picoclaw\"><img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"><br><b>PicoClaw</b></a><br> <sub>⭐ 14,6 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/zeroclaw-labs/zeroclaw\"><img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"><br><b>ZeroClaw</b></a><br> <sub>⭐ 9,9 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/nearai/ironclaw\"><img src=\"./public/providers/ironclaw.png\" alt=\"Železný dráp\" width=\"48\"><br><b>Železný dráp</b></a><br> <sub>⭐ 2,1 tisíce</sub> </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anomalyco/opencode\"><img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"><br><b>OpenCode</b></a><br> <sub>⭐ 106 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/openai/codex\"><img src=\"./public/providers/codex.png\" alt=\"Codex CLI\" width=\"48\"><br><b>Codex CLI</b></a><br> <sub>⭐ 60,8 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/anthropics/claude-code\"><img src=\"./public/providers/claude.png\" alt=\"Claude Code\" width=\"48\"><br><b>Claude Code</b></a><br> <sub>⭐ 67,3 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/google-gemini/gemini-cli\"><img src=\"./public/providers/gemini-cli.png\" alt=\"Gemini CLI\" width=\"48\"><br> <b>Gemini CLI</b></a><br> <sub>⭐ 94,7 tisíc</sub> </td>\n <td align=\"center\" width=\"110\"> <a href=\"https://github.com/Kilo-Org/kilocode\"><img src=\"./public/providers/kilocode.png\" alt=\"Kilo kód\" width=\"48\"><br><b>Kilo kód</b></a><br> <sub>⭐ 15,5 tisíc</sub> </td>\n </tr>\n </table>\n\n<sub>📡 Všichni agenti se připojují přes <code>http://localhost:20128/v1</code> nebo <code>http://cloud.omniroute.online/v1</code> — jedna konfigurace, neomezené modely a kvóty</sub>\n\n---\n\n## 🤔 Proč OmniRoute?\n\n**Přestaňte plýtvat penězi a narážet na limity:**\n\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Kvóta předplatného vyprší každý měsíc\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Limity rychlosti vám zabrání v kódování\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Drahá API (20–50 USD/měsíc na poskytovatele)\n- <img src=\"https://img.shields.io/badge/%E2%9C%97-e74c3c?style=flat-square\" height=\"16\"> Ruční přepínání mezi poskytovateli\n\n**OmniRoute to řeší:**\n\n- ✅ **Maximalizujte předplatné** – Sledujte kvótu, využijte každou částku před resetováním\n- ✅ **Automatické záložní** – Předplatné → API klíč → Levné → Zdarma, žádné výpadky\n- ✅ **Více účtů** – Round-robin mezi účty u jednotlivých poskytovatelů\n- ✅ **Univerzální** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakýmkoli nástrojem CLI\n\n---\n\n## 📧 Podpora\n\n> 💬 **Přidejte se k naší komunitě!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získejte pomoc, sdílejte tipy a buďte v obraze.\n\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problémy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitní skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Přispívání** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevřete žádost o příspěvek nebo si vyberte `good first issue`\n- **Původní projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### 🐛 Hlásíte chybu?\n\nPři otevírání problému spusťte příkaz system-info a přiložte vygenerovaný soubor:\n\n```bash\nnpm run system-info\n```\n\nTím se vygeneruje soubor `system-info.txt` s verzí Node.js, verzí OmniRoute, podrobnostmi o operačním systému, nainstalovanými nástroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systémovými balíčky – vše, co potřebujeme k rychlé reprodukci vašeho problému. Soubor přiložte přímo k vašemu problému na GitHubu.\n\n---\n\n## 🔄 Jak to funguje\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 Co řeší OmniRoute — 30 skutečných problémů a případů použití\n\n> **Každý vývojář používající nástroje umělé inteligence se s těmito problémy setkává denně.** OmniRoute byl vytvořen tak, aby je všechny vyřešil – od překročení nákladů po regionální bloky, od nefunkčních toků OAuth až po operace s protokoly a sledovatelnost v podniku.\n\n<details>\n<summary><b>💸 1. „Platím si drahé předplatné, ale stále mě ruší limity“</b></summary>\n</details>\n\nVývojáři platí za Claude Pro, Codex Pro nebo GitHub Copilot 20–200 dolarů měsíčně. I při platbě má kvóta strop – 5 hodin používání, týdenní limity nebo limity rychlosti za minutu. Uprostřed kódovací relace poskytovatel přestane reagovat a vývojář ztrácí plynulost a produktivitu.\n\n**Jak to OmniRoute řeší:**\n\n- **Inteligentní čtyřúrovňová záložní služba** – Pokud dojde kvóta předplatného, ​​automaticky se přesměruje na API klíč → Levné → Zdarma bez manuálního zásahu\n- **Sledování kvót v reálném čase** – Zobrazuje spotřebu tokenů v reálném čase s odpočítáváním resetování (5 hodin, denně, týdně)\n- **Podpora více účtů** – Více účtů u jednoho poskytovatele s automatickým přepínáním – když jeden dojde, přepne se na další\n- **Vlastní kombinace** — Přizpůsobitelné záložní řetězce se 6 strategiemi vyvažování (fill-first, round robin, P2C, náhodné, nejméně používané, nákladově optimalizované)\n- **Codex Business Quotas** — Sledování kvót pracovního prostoru firmy/týmu přímo v dashboardu\n\n<details>\n<summary><b>🔌 2. „Potřebuji použít více poskytovatelů, ale každý má jiné API“</b></summary>\n</details>\n\nOpenAI používá jeden formát, Claude (Anthropic) jiný a Gemini ještě třetí. Pokud chce vývojář testovat modely od různých poskytovatelů nebo mezi nimi přecházet, musí překonfigurovat SDK, změnit koncové body a vypořádat se s nekompatibilními formáty. Vlastní poskytovatelé (FriendLI, NIM) mají nestandardní koncové body modelů.\n\n**Jak to OmniRoute řeší:**\n\n- **Sjednocený koncový bod** — Jeden `http://localhost:20128/v1` slouží jako proxy pro všech 44+ poskytovatelů.\n- **Překlad formátu** — Automatický a transparentní: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Sanitizace odpovědí** — Odstraňuje nestandardní pole ( `x_groq` , `usage_breakdown` , `service_tier` ), která porušují OpenAI SDK v1.83+\n- **Normalizace rolí** — Převádí `developer` → `system` pro poskytovatele bez OpenAI; `system` → `user` pro GLM/ERNIE\n- **Extrakce tagů Think** — Extrahuje bloky `<think>` z modelů, jako je DeepSeek R1, do standardizovaného `reasoning_content`\n- **Strukturovaný výstup pro Gemini** — `json_schema` → automatická konverze `responseMimeType` / `responseSchema`\n- **Výchozí hodnota `stream` je `false`** – Odpovídá specifikaci OpenAI, čímž se zabrání neočekávanému SSE v Python/Rust/Go SDK.\n\n<details>\n<summary><b>🌐 3. „Můj poskytovatel AI blokuje můj region/zemi“</b></summary>\n</details>\n\nPoskytovatelé jako OpenAI/Codex blokují přístup z určitých geografických oblastí. Uživatelé se během připojení OAuth a API dostávají k chybám jako `unsupported_country_region_territory` . To je obzvláště frustrující pro vývojáře z rozvojových zemí.\n\n**Jak to OmniRoute řeší:**\n\n- **3úrovňová konfigurace proxy** – Konfigurovatelná proxy na 3 úrovních: globální (veškerý provoz), pro jednotlivé poskytovatele (pouze jeden poskytovatel) a pro jednotlivé připojení/klíč\n- **Barevně kódované odznaky proxy** – Vizuální indikátory: 🟢 globální proxy, 🟡 proxy poskytovatele, 🔵 proxy připojení, vždy zobrazující IP adresu\n- **Výměna tokenů OAuth prostřednictvím proxy** – tok OAuth také prochází přes proxy, čímž se řeší `unsupported_country_region_territory`\n- **Testy připojení přes proxy** – Testy připojení používají nakonfigurovaný proxy (již žádné přímé obcházení)\n- **Podpora SOCKS5** — Plná podpora proxy SOCKS5 pro odchozí směrování\n- **TLS Fingerprint Spoofing** — Otisk prstu TLS podobný prohlížeči pomocí `wreq-js` pro obcházení detekce botů\n- **🔏 Porovnávání otisků prstů v CLI** — Změní pořadí záhlaví a polí v těle serveru tak, aby odpovídala nativním binárním podpisům v CLI, čímž drasticky snižuje riziko nahlašování účtu. IP adresa proxy je zachována — získáte současně stealth **i** maskování IP adresy.\n\n<details>\n<summary><b>🆓 4. „Chci používat umělou inteligenci pro kódování, ale nemám peníze“</b></summary>\n</details>\n\nNe každý si může dovolit zaplatit 20–200 dolarů měsíčně za předplatné AI. Studenti, vývojáři z rozvíjejících se zemí, amatéři a freelanceři potřebují přístup ke kvalitním modelům za nulovou cenu.\n\n**Jak to OmniRoute řeší:**\n\n- **Vestavění poskytovatelé bezplatné úrovně** — Nativní podpora pro 100% bezplatné poskytovatele: iFlow (5 neomezených modelů přes OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezené modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisíc tokenů/měsíc zdarma)\n- **Ollama Cloud** — Cloudově hostované modely Ollama na `api.ollama.com` s bezplatnou úrovní „Light usage“; použijte prefix `ollamacloud/<model>`\n- **Kombinace pouze zdarma** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/měsíc s nulovými prostoji\n- **NVIDIA NIM Free Access** — ~40 RPM developerský přístup k více než 70 modelům na build.nvidia.com (přechod z kreditů na čisté limity rychlosti)\n- **Strategie optimalizace nákladů** – Strategie směrování, která automaticky vybere nejlevnějšího dostupného poskytovatele\n\n<details>\n<summary><b>🔒 5. „Potřebuji chránit svou bránu umělé inteligence před neoprávněným přístupem“</b></summary>\n</details>\n\nPři zpřístupnění brány umělé inteligence síti (LAN, VPS, Docker) může kdokoli s adresou spotřebovat tokeny/kvótu vývojáře. Bez ochrany jsou API zranitelná vůči zneužití, prompt injection a dalšímu zneužití.\n\n**Jak to OmniRoute řeší:**\n\n- **Správa klíčů API** – generování, rotace a vymezování rozsahu pro každého poskytovatele s vyhrazenou stránkou `/dashboard/api-manager`\n- **Oprávnění na úrovni modelu** – Omezení klíčů API na konkrétní modely ( `openai/*` , zástupné znaky) pomocí přepínače Povolit vše/Omezit\n- **Ochrana koncových bodů API** – Vyžaduje klíč pro `/v1/models` a blokuje konkrétní poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** — Všechny trasy dashboardu chráněné middlewarem `withAuth` + tokeny CSRF\n- **Omezovač rychlosti** — Omezování rychlosti na IP s konfigurovatelnými okny\n- **Filtrování IP adres** — Seznam povolených/blokovaných adres pro řízení přístupu\n- **Ochrana proti vkládání výzev** – Sanitizace proti škodlivým vzorcům výzev\n- **Šifrování AES-256-GCM** – přihlašovací údaje jsou v klidovém stavu šifrovány\n\n<details>\n<summary><b>🛑 6. „Můj poskytovatel selhal a já ztratil/a programovací tok“</b></summary>\n</details>\n\nPoskytovatelé umělé inteligence se mohou stát nestabilními, vracet chyby 5xx nebo dosáhnout dočasných limitů rychlosti. Pokud je vývojář závislý na jediném poskytovateli, je jeho práce přerušena. Bez jističů může opakované pokusy vést k pádu aplikace.\n\n**Jak to OmniRoute řeší:**\n\n- **Jistič pro každý model** – Automatické otevírání/zavírání s konfigurovatelnými prahovými hodnotami a dobou ochlazování (Zavřeno/Otevřeno/Poloviční otevření), rozsah definovaný pro každý model, aby se zabránilo kaskádování bloků\n- **Exponenciální odklad** — Progresivní zpoždění opakování\n- **Anti-Thundering Herd** — ochrana Mutex + semafor proti souběžným bouřím s opakovanými pokusy\n- **Kombinované záložní řetězce** – Pokud primární poskytovatel selže, automaticky se propadne řetězcem bez zásahu.\n- **Kombinovaný jistič** – Automaticky deaktivuje selhávajícího poskytovatele v rámci kombinovaného řetězce\n- **Dashboard stavu** — Monitorování provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti, latence p50/p95/p99\n\n<details>\n<summary><b>🔧 7. „Konfigurace každého nástroje umělé inteligence je zdlouhavá a opakující se“</b></summary>\n</details>\n\nVývojáři používají Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Každý nástroj potřebuje jinou konfiguraci (API endpoint, klíč, model). Překonfigurování při změně poskytovatele nebo modelu je ztráta času.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel nástrojů CLI** — Vyhrazená stránka s nastavením jedním kliknutím pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generátor konfigurace GitHub Copilot** – Generuje `chatLanguageModels.json` pro VS Code s hromadným výběrem modelu\n- **Průvodce zaváděním** – 4krokové nastavení pro začínající uživatele\n- **Jeden koncový bod, všechny modely** – jednou nakonfigurujte `http://localhost:20128/v1` a získejte přístup k více než 44 poskytovatelům\n\n<details>\n<summary><b>🔑 8. „Správa OAuth tokenů od více poskytovatelů je peklo“</b></summary>\n</details>\n\nClaude Code, Codex, Gemini CLI, Copilot – všechny používají OAuth 2.0 s tokeny s vypršením platnosti. Vývojáři se musí neustále znovu autentizovat, řešit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdálených serverech. Obzvláště problematický je OAuth v LAN/VPS.\n\n**Jak to OmniRoute řeší:**\n\n- **Automatická aktualizace tokenů** – Tokeny OAuth se obnovují na pozadí před vypršením platnosti.\n- **Vestavěný OAuth 2.0 (PKCE)** – Automatický tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** — Více účtů na poskytovatele prostřednictvím extrakce tokenů JWT/ID\n- **OAuth LAN/Remote Fix** — Detekce privátní IP adresy pro `redirect_uri` + manuální režim URL pro vzdálené servery\n- **OAuth Behind Nginx** — Používá `window.location.origin` pro kompatibilitu s reverzní proxy\n- **Průvodce vzdáleným OAuth** – Podrobný návod k přihlašovacím údajům Google Cloud na VPS/Dockeru\n\n<details>\n<summary><b>📊 9. „Nevím, kolik utrácím ani kde“</b></summary>\n</details>\n\nVývojáři používají více placených poskytovatelů, ale nemají jednotný přehled o výdajích. Každý poskytovatel má svůj vlastní fakturační panel, ale neexistuje žádný konsolidovaný přehled. Mohou se hromadit neočekávané náklady.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard pro analýzu nákladů** – Sledování nákladů na token a správa rozpočtu pro každého poskytovatele\n- **Rozpočtové limity na úroveň** – Strop výdajů na úroveň, který spouští automatický záložní režim\n- **Konfigurace cen podle modelu** – Konfigurovatelné ceny podle modelu\n- **Statistiky použití pro každý klíč API** — Počet požadavků a časové razítko posledního použití pro každý klíč\n- **Analytický panel** – Statistické karty, graf využití modelu, tabulka poskytovatelů s mírou úspěšnosti a latencí\n\n<details>\n<summary><b>🐛 10. „Nedokážu diagnostikovat chyby a problémy ve volání umělé inteligence.“</b></summary>\n</details>\n\nKdyž volání selže, vývojář neví, zda se jednalo o limit rychlosti, vypršelý token, špatný formát nebo chybu poskytovatele. Fragmentované protokoly napříč různými terminály. Bez sledovatelnosti je ladění metodou pokus-omyl.\n\n**Jak to OmniRoute řeší:**\n\n- **Panel jednotných protokolů** – 4 karty: Protokoly požadavků, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlížeč protokolů konzole** — Prohlížeč protokolů v reálném čase ve stylu terminálu s barevně kódovanými úrovněmi, automatickým posouváním, vyhledáváním a filtrováním\n- **Protokoly proxy SQLite** – trvalé protokoly, které přežijí restart serveru\n- **Překladačské hřiště** — 4 režimy ladění: Hřiště (překlad formátu), Tester chatu (okružní), Testovací stůl (dávkový), Živý monitor (v reálném čase)\n- **Telemetrie požadavků** — latence p50/p95/p99 + trasování X-Request-Id\n- **Souborové protokolování s rotací** – Konzolový interceptor zachycuje vše do protokolu JSON s rotací na základě velikosti\n- **Zpráva o systémových informacích** — příkaz `npm run system-info` vygeneruje `system-info.txt` s kompletním popisem vašeho prostředí (verze uzlu, verze OmniRoute, operační systém, nástroje CLI, stav Dockeru/PM2). Přiložte jej při hlášení problémů pro okamžité třídění.\n\n<details>\n<summary><b>🏗️ 11. „Nasazení a údržba brány je složitá“</b></summary>\n</details>\n\nInstalace, konfigurace a údržba AI proxy v různých prostředích (lokální, VPS, Docker, cloud) je pracná. Problémy, jako jsou pevně zakódované cesty, `EACCES` u adresářů, konflikty portů a multiplatformní sestavení, přispívají k obtížím.\n\n**Jak to OmniRoute řeší:**\n\n- **npm globální instalace** — `npm install -g omniroute && omniroute` — hotovo\n- **Docker Multi-Platform** — AMD64 + nativní ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** — `base` (bez nástrojů CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopová aplikace Electron** — Nativní aplikace pro Windows/macOS/Linux se systémovou lištou, automatickým spuštěním a offline režimem\n- **Režim rozdělených portů** – API a řídicí panel na samostatných portech pro pokročilé scénáře (reverzní proxy, síťování kontejnerů)\n- **Cloud Sync** – Konfigurace synchronizace mezi zařízeními pomocí Cloudflare Workers\n- **Zálohy databází** — Automatické zálohování, obnovení, export a import všech nastavení\n\n<details>\n<summary><b>🌍 12. „Rozhraní je pouze v angličtině a můj tým nemluví anglicky“</b></summary>\n</details>\n\nTýmy v neanglicky mluvících zemích, zejména v Latinské Americe, Asii a Evropě, se potýkají s rozhraními pouze v angličtině. Jazykové bariéry snižují míru přijetí a zvyšují chyby v konfiguraci.\n\n**Jak to OmniRoute řeší:**\n\n- **Dashboard i18n — 30 jazyků** — Všech 500+ kláves je přeloženo včetně arabštiny, bulharštiny, dánštiny, němčiny, španělštiny, finštiny, francouzštiny, hebrejštiny, hindštiny, maďarštiny, indonéštiny, italštiny, japonštiny, korejštiny, malajštiny, holandštiny, norštiny, polštiny, portugalštiny (PT/BR), rumunštiny, ruštiny, slovenštiny, švédštiny, thajštiny, ukrajinštiny, vietnamštiny, čínštiny, filipínštiny a angličtiny\n- **Podpora RTL** – Podpora psaní zprava doleva pro arabštinu a hebrejštinu\n- **Vícejazyčné soubory README** — 30 kompletních překladů dokumentace\n- **Výběr jazyka** — Ikona glóbu v záhlaví pro přepínání v reálném čase\n\n<details>\n<summary><b>🔄 13. „Potřebuji víc než jen chat – potřebuji vložené soubory, obrázky, zvuk.“</b></summary>\n</details>\n\nUmělá inteligence není jen dokončování chatu. Vývojáři potřebují generovat obrázky, přepisovat zvuk, vytvářet embeddedy pro RAG, měnit pořadí dokumentů a moderovat obsah. Každé API má jiný koncový bod a formát.\n\n**Jak to OmniRoute řeší:**\n\n- **Vkládání** — `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generování obrázků** — `/v1/images/generations` s 10 poskytovateli a více než 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Převod textu na video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Převod textu na hudbu** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Přepis zvuku** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Převod textu na řeč** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a další stávající poskytovatelé\n- **Moderování** — `/v1/moderations` — Kontroly bezpečnosti obsahu\n- **Změna pořadí** — `/v1/rerank` — Změna pořadí relevance dokumentu\n- **Responses API** — Plná podpora `/v1/responses` pro Codex\n\n<details>\n<summary><b>🧪 14. „Nemám způsob, jak testovat a porovnávat kvalitu napříč modely.“</b></summary>\n</details>\n\nVývojáři chtějí vědět, který model je pro jejich případ použití nejlepší – kód, překlad, uvažování – ale ruční porovnávání je pomalé. Neexistují žádné integrované nástroje pro vyhodnocování.\n\n**Jak to OmniRoute řeší:**\n\n- **Hodnocení LLM** — Testování Golden setu s 10 předinstalovanými případy zahrnujícími pozdravy, matematiku, geografii, generování kódu, dodržování JSON, překlad, markdown, odmítnutí bezpečnostních požadavků\n- **4 strategie shody** — `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovací lavice pro překladatelské hřiště** — Dávkové testování s více vstupy a očekávanými výstupy, porovnání napříč poskytovateli\n- **Tester chatu** — Kompletní okružní cesta s vizuálním vykreslováním odpovědí\n- **Živý monitor** — Stream všech požadavků procházejících proxy serverem v reálném čase\n\n<details>\n<summary><b>📈 15. „Potřebuji škálovat bez ztráty výkonu“</b></summary>\n</details>\n\nS rostoucím objemem požadavků generují stejné otázky bez ukládání do mezipaměti duplicitní náklady. Bez idempotence duplicitní požadavky plýtvají zpracováním. Je nutné dodržovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute řeší:**\n\n- **Sémantická mezipaměť** — Dvouvrstvá mezipaměť (signatura + sémantika) snižuje náklady a latenci\n- **Idempotence požadavku** — 5s deduplikační okno pro identické požadavky\n- **Detekce limitu rychlosti** – sledování otáček za minutu (RPM), minimální mezera a maximální souběžné sledování pro každého poskytovatele\n- **Upravitelné limity rychlosti** — Konfigurovatelné výchozí hodnoty v Nastavení → Odolnost s perzistencí\n- **Mezipaměť pro ověření klíčů API** — třívrstvá mezipaměť pro výkon produkčního prostředí\n- **Dashboard s telemetrií** – latence p50/p95/p99, statistiky mezipaměti, dostupnost\n\n<details>\n<summary><b>🤖 16. „Chci mít chování modelů globálně pod kontrolou“</b></summary>\n</details>\n\nVývojáři, kteří chtějí všechny odpovědi v určitém jazyce, se specifickým tónem nebo chtějí omezit tokeny pro uvažování. Konfigurace této funkce v každém nástroji/požadavku je nepraktická.\n\n**Jak to OmniRoute řeší:**\n\n- **Vložení systémového prompt** – Globální prompt aplikovaný na všechny požadavky\n- **Validace rozpočtu Thinking** — Řízení alokace tokenů na požadavek (průchozí, automatické, vlastní, adaptivní)\n- **6 strategií směrování** – Globální strategie, které určují, jak jsou požadavky distribuovány\n- **Směrovač se zástupnými znaky** — vzory `provider/*` dynamicky směrují k libovolnému poskytovateli\n- **Přepínání povolení/zakázání kombinací** – Přepínání kombinací přímo z řídicího panelu\n- **Přepínání poskytovatele** – Povolení/zakázání všech připojení pro poskytovatele jedním kliknutím\n- **Blokovaní poskytovatelé** – Vyloučení konkrétních poskytovatelů ze seznamu `/v1/models`\n\n<details>\n<summary><b>🧰 17. „Potřebuji nástroje MCP jako prvotřídní produktové funkce.“</b></summary>\n</details>\n\nMnoho bran umělé inteligence odhaluje MCP pouze jako skrytý implementační detail. Týmy potřebují viditelnou a spravovatelnou operační vrstvu.\n\n**Jak to OmniRoute řeší:**\n\n- MCP se zobrazuje v navigaci na řídicím panelu a na kartě protokolu koncového bodu.\n- Vyhrazená stránka pro správu MCP s procesy, nástroji, rozsahy a auditem\n- Vestavěný rychlý start pro `omniroute --mcp` a onboarding klienta\n\n<details>\n<summary><b>🧠 18. „Potřebuji orchestraci A2A se synchronizací a cestami úloh streamu.“</b></summary>\n</details>\n\nPracovní postupy agentů vyžadují jak přímé odpovědi, tak dlouhodobé streamované provádění s kontrolou životního cyklu.\n\n**Jak to OmniRoute řeší:**\n\n- Koncový bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamování SSE s šířením stavu terminálu\n- Rozhraní API životního cyklu úloh pro `tasks/get` a `tasks/cancel`\n\n<details>\n<summary><b>🛰️ 19. „Potřebuji skutečný stav procesu MCP, ne odhadovaný stav.“</b></summary>\n</details>\n\nProvozní týmy potřebují vědět, zda je MCP skutečně aktivní, nejen zda je API dosažitelné.\n\n**Jak to OmniRoute řeší:**\n\n- Soubor běhového heartbeatu s PID, časovými razítky, transportem, počtem nástrojů a režimem rozsahu\n- API stavu MCP kombinující prezenční signál a nedávnou aktivitu\n- Karty stavu uživatelského rozhraní pro zobrazení aktuálnosti procesů/provozuschopnosti/prezenčního signálu\n\n<details>\n<summary><b>📋 20. „Potřebuji auditovatelné provedení nástroje MCP“</b></summary>\n</details>\n\nKdyž nástroje mění konfiguraci nebo spouštějí operační akce, týmy potřebují forenzní sledovatelnost.\n\n**Jak to OmniRoute řeší:**\n\n- Protokolování auditu pro volání nástrojů MCP s podporou SQLite\n- Filtruje podle nástroje, úspěchu/neúspěchu, klíče API a stránkování\n- Tabulka auditu dashboardu + koncové body statistik pro automatizaci\n\n<details>\n<summary><b>🔐 21. „Potřebuji omezená oprávnění MCP pro každou integraci.“</b></summary>\n</details>\n\nRůzní klienti by měli mít přístup ke kategoriím nástrojů s nejnižšími oprávněními.\n\n**Jak to OmniRoute řeší:**\n\n- 9 detailních MCP sond pro kontrolovaný přístup k nástrojům\n- Vynucení rozsahu a viditelnost v uživatelském rozhraní správy MCP\n- Bezpečná výchozí poloha pro provozní nástroje\n\n<details>\n<summary><b>⚙️ 22. „Potřebuji provozní kontroly bez nutnosti přesouvání“</b></summary>\n</details>\n\nTýmy potřebují rychlé změny v běhovém prostředí během incidentů nebo nákladových událostí.\n\n**Jak to OmniRoute řeší:**\n\n- Přepněte aktivaci komba přímo z řídicího panelu MCP\n- Používejte profily odolnosti z předdefinovaných balíčků zásad\n- Resetujte stav jističe ze stejného ovládacího panelu\n\n<details>\n<summary><b>🔄 23. „Potřebuji živý přehled o životním cyklu úkolů A2A a jejich zrušení.“</b></summary>\n</details>\n\nBez přehledu o životním cyklu je obtížné třídit incidenty úkolů.\n\n**Jak to OmniRoute řeší:**\n\n- Výpis/filtrování úkolů podle státu/dovednosti s stránkováním\n- Podrobný přehled metadat úloh, událostí a artefaktů\n- Koncový bod zrušení úlohy a akce uživatelského rozhraní s potvrzením\n\n<details>\n<summary><b>🌊 24. „Potřebuji metriky aktivního streamu pro A2A zátěž“</b></summary>\n</details>\n\nStreamovací pracovní postupy vyžadují provozní přehled o souběžnosti a živých připojeních.\n\n**Jak to OmniRoute řeší:**\n\n- Čítače aktivních streamů integrované do stavu A2A\n- Časové razítko posledního úkolu a počty pro jednotlivé stavy\n- Karty A2A dashboardu pro monitorování provozu v reálném čase\n\n<details>\n<summary><b>🪪 25. „Potřebuji standardní vyhledávání agentů pro klienty“</b></summary>\n</details>\n\nExterní klienti a orchestratoři potřebují pro onboarding strojově čitelná metadata.\n\n**Jak to OmniRoute řeší:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazené v uživatelském rozhraní pro správu\n- API pro stav A2A zahrnuje metadata pro zjišťování pro automatizaci\n\n<details>\n<summary><b>🧭 26. „Potřebuji v uživatelském rozhraní produktu zjistitelnost protokolu.“</b></summary>\n</details>\n\nPokud uživatelé nemohou objevit protokolové povrchy, kvalita přijetí a podpory klesá.\n\n**Jak to OmniRoute řeší:**\n\n- Stránka Konsolidované **koncové body** s kartami pro koncové body Proxy, MCP, A2A a API\n- Přepínání stavu inline služby (Online/Offline) pro MCP a A2A\n- Odkazy z přehledu na vyhrazené karty pro správu\n\n<details>\n<summary><b>🧪 27. „Potřebuji komplexní ověření protokolu se skutečnými klienty.“</b></summary>\n</details>\n\nSimulované testy nestačí k ověření kompatibility protokolu před vydáním.\n\n**Jak to OmniRoute řeší:**\n\n- Sada E2E, která spouští aplikaci a používá skutečný transport klienta MCP SDK.\n- Klientské testy A2A pro toky zjišťování, odesílání, streamování, načítání a zrušení\n- Křížová kontrola tvrzení oproti API pro audit MCP a úkoly A2A\n\n<details>\n<summary><b>📡 28. „Potřebuji jednotnou pozorovatelnost napříč všemi rozhraními“</b></summary>\n</details>\n\nRozdělení pozorovatelnosti podle protokolu vytváří slepá místa a delší MTTR.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocené dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie požadavků napříč vrstvami OpenAI, MCP a A2A\n- Provozní API pro stav a automatizaci\n\n<details>\n<summary><b>💼 29. „Potřebuji jeden runtime pro proxy + nástroje + orchestraci agentů“</b></summary>\n</details>\n\nSpouštění mnoha samostatných služeb zvyšuje provozní náklady a počet poruch.\n\n**Jak to OmniRoute řeší:**\n\n- Proxy, MCP server a A2A server kompatibilní s OpenAI v jednom balíčku\n- Sdílené ověřování, odolnost, úložiště dat a pozorovatelnost\n- Konzistentní model politik napříč všemi interakčními plochami\n\n<details>\n<summary><b>🚀 30. „Potřebuji agentské pracovní postupy bez slepení kódu.“</b></summary>\n</details>\n\nTýmy ztrácejí rychlost při spojování více ad-hoc služeb a skriptů.\n\n**Jak to OmniRoute řeší:**\n\n- Sjednocená strategie koncových bodů pro klienty a agenty\n- Vestavěná uživatelská rozhraní pro správu protokolů a cesty pro ověřování kouře\n- Základy připravené pro produkční prostředí (zabezpečení, protokolování, odolnost, zálohování)\n\n### Příklady herních plánů (integrované případy užití)\n\n**Příručka A: Maximalizace placeného předplatného + levné zálohování**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Příručka B: Kódovací stack s nulovými náklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Příručka C: Nonstop záložní řetězec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Příručka D: Operace agentů s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Začněte zdarma — Nulové náklady na konfiguraci\n\n> Nastavte si kódování s umělou inteligencí během několika minut za **0 $/měsíc** . Propojte tyto bezplatné účty a využijte vestavěnou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelé odemčeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Připojení **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 – **neomezeně** |\n| 2 | Připojení k **iFlow** (Google OAuth) | kimi-k2-myšlení, qwen3-coder-plus, deepseek-r1... — **neomezeně** |\n| 3 | Připojení **Qwen** (kód zařízení) | qwen3-coder-plus, qwen3-coder-flash... — **neomezeně** |\n| 4 | Připojení **rozhraní příkazového řádku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180 000 GBP/měsíc zdarma** |\n| 5 | `/dashboard/combos` → Šablona **Free Stack (0 $)** | Automatické zařazení všech bezplatných poskytovatelů do routingu |\n\n**V libovolném IDE/CLI naveďte:** `http://localhost:20128/v1` · Klíč API: `any-string` · Hotovo.\n\n> **Volitelné doplňkové krytí (také zdarma):** Groq API klíč (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelů), Cerebras (1 milion tok/den).\n\n## ⚡ Rychlý start\n\n### 1) Nainstalujte a spusťte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uživatelé pnpm:** Po instalaci spusťte `pnpm approve-builds -g` , abyste povolili nativní skripty pro sestavení vyžadované programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard se otevírá na `http://localhost:20128` a základní URL API je `http://localhost:20128/v1` .\n\n| Příkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuštění serveru ( `PORT=20128` , API a dashboard na stejném portu) |\n| `omniroute --port 3000` | Nastavte kanonický/API port na 3000 |\n| `omniroute --mcp` | Spuštění MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevírat prohlížeč automaticky |\n| `omniroute --help` | Zobrazit nápovědu |\n\nVolitelný režim s rozděleným portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Připojte poskytovatele a vytvořte si klíč API\n\n1. Otevřete Dashboard → `Providers` a připojte alespoň jednoho poskytovatele (klíč OAuth nebo API).\n2. Otevřete Dashboard → `Endpoints` a vytvořte API klíč.\n3. (Volitelné) Otevřete Dashboard → `Combos` a nastavte záložní řetězec.\n\n### 3) Nasměrujte svůj kódovací nástroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilními s OpenAI.\n\n### 4) Povolení a ověření protokolů (v2.0)\n\n**MCP (pro operace řízené nástroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak připojte svého MCP klienta přes `stdio` a otestujte nástroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovní postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ověřte vše od začátku do konce (doporučeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ověřuje skutečné toky klientů MCP a A2A v porovnání se spuštěnou aplikací.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## 🐳 Docker\n\nOmniRoute je k dispozici jako veřejný obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlý běh:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostředí:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Používání Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | Štítek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovější stabilní verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuální verze |\n\n---\n\n## 🖥️ Desktopová aplikace – offline a vždy zapnutá\n\n> 🆕 **NOVINKA!** OmniRoute je nyní k dispozici jako **nativní desktopová aplikace** pro Windows, macOS a Linux.\n\nSpusťte OmniRoute jako samostatnou desktopovou aplikaci – pro lokální modely není potřeba žádný terminál, prohlížeč ani internet. Aplikace založená na platformě Electron obsahuje:\n\n- 🖥️ **Nativní okno** — Vyhrazené okno aplikace s integrací do systémové lišty\n- 🔄 **Automatické spuštění** — Spuštění OmniRoute po přihlášení do systému\n- 🔔 **Nativní oznámení** – Získejte upozornění na vyčerpání kvóty nebo problémy s poskytovateli\n- ⚡ **Instalace jedním kliknutím** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline režim** — Funguje plně offline s přiloženým serverem\n\n### Rychlý start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systémový zásobník\n\nPo minimalizaci se OmniRoute nachází v systémové liště a nabízí rychlé akce:\n\n- Otevřít řídicí panel\n- Změnit port serveru\n- Ukončit aplikaci\n\n📖 Úplná dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Přehled cen\n\n| Úroveň | Poskytovatel | Náklady | Obnovení kvóty | Nejlepší pro |\n| --------------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **💳 PŘEDPLATNÉ** | Claude Code (profesionál) | 20 dolarů měsíčně | 5 hodin + týdně | Již přihlášen/a k odběru |\n| Kodex (Plus/Pro) | 20–200 USD/měsíc | 5 hodin + týdně | Uživatelé OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisíc měsíčně + 1 tisíc denně | Každý! |\n| GitHub Copilot | 10–19 USD/měsíc | Měsíční | Uživatelé GitHubu |\n| **🔑 KLÍČ API** | NVIDIA NIM | **ZDARMA** (vývoj navždy) | ~40 ot./min | 70+ otevřených modelů |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší na světě |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisíc otáček za minutu | Ultrarychlá lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | Žádný | Nejlepší zdůvodnění ceny a kvality |\n| xAI Grok-4 Rychlý | **0,20/0,50 USD za 1 milion** 🆕 | Žádný | Nejrychlejší + volání nástroje, ultranízké |\n| xAI Grok-4 (standardní) | 0,20/1,50 USD za 1 milion 🆕 | Žádný | Vlajková loď Reasoning od xAI |\n| Mistral | Zkušební verze zdarma + placené | Omezená sazba | Evropská umělá inteligence |\n| OpenRouter | Platba za použití | Žádný | Více než 100 modelů agregováno. |\n| **💰 LEVNÉ** | GLM-5 (přes Z.AI) 🆕 | 0,5 USD/1 milion | Denně v 10:00 | Výstup 128 tisíc obrazových bodů, nejnovější vlajková loď |\n| GLM-4.7 | 0,6 USD/1 milion | Denně v 10:00 | Záloha rozpočtu |\n| MiniMax M2.5 🆕 | Vstup 0,3 USD/1 milion | 5hodinové válcování | Úvaha + agentní úkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinové válcování | Nejlevnější varianta |\n| Kimi K2.5 (Moonshot API) 🆕 | Platba za použití | Žádný | Přímý přístup k Moonshot API |\n| Kimi K2 | 9 dolarů měsíčně bez závazků | 10 milionů tokenů/měsíc | Předvídatelné náklady |\n| **🆓 ZDARMA** | iFlow | **0 dolarů** | Neomezený | 5 modelů neomezeně |\n| Qwen | **0 dolarů** | Neomezený | 4 modely neomezeně |\n| Kiro | **0 dolarů** | Neomezený | Claude Sonnet/Haiku (tvorce AWS) |\n\n> 🆕 **Přidány nové modely (březen 2026):** řada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkováno na 1143 ms – o 30 % rychlejší než Gemini 2.5 Flash), GLM-5 přes Z.AI s výstupem 128K, uvažování MiniMax M2.5, aktualizované ceny DeepSeek V3.2, Kimi K2.5 přes Moonshot Direct API.\n\n**💡 Kombinovaný balík za 0 $ — Kompletní bezplatná instalace:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\niFlow (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Nulové náklady. Nikdy nepřestávejte s kódováním.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a všechny záložní režimy se provede automaticky – žádné ruční přepínání.\n\n---\n\n---\n\n## 🆓 Bezplatné modely – Co skutečně získáte\n\n> Všechny níže uvedené modely jsou **100% zdarma a nevyžadují žádnou kreditní kartu** . OmniRoute mezi nimi automaticky propojí trasy, když dojde jedna kvóta – zkombinujte je všechny a získejte tak nerozlučnou kombinaci za 0 dolarů.\n\n### 🔵 CLAUDE MODELS (přes Kiro — AWS Builder ID)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezený** | Žádný hlášený denní limit |\n| `claude-opus-4.6` | `kr/` | **Neomezený** | Nejnovější opus od Kira |\n\n### 🟢 MODELY IFLOW (Bezplatné OAuth — bez nutnosti platit kreditní kartou)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-plus` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `deepseek-r1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `minimax-m2.1` | `if/` | **Neomezený** | Žádný hlášený strop |\n| `kimi-k2` | `if/` | **Neomezený** | Žádný hlášený strop |\n\n### 🟡 MODELY QWEN (Ověření kódu zařízení)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `qwen3-coder-next` | `qw/` | **Neomezený** | Žádný hlášený strop |\n| `vision-model` | `qw/` | **Neomezený** | Multimodální (obrázky) |\n\n### 🟣 Rozhraní GEMINI CLI (Google OAuth)\n\n| Model | Předpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisíc tok/měsíc** + 1 tisíc/den | Měsíční reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisíc měsíčně (sdílený bazén) | Vysoká kvalita |\n\n### ⚫ NVIDIA NIM (Bezplatný klíč API — build.nvidia.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vývojář) | Žádný limit tokenů | **~40 ot./min** | Více než 70 modelů; přechod na čisté limity sazeb v polovině roku 2025 |\n\nOblíbené bezplatné modely: `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`\n\n### ⚪ CEREBRAS (Bezplatný klíč API — inference.cerebras.ai)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenů/den** | 60 000 otáček za minutu / 30 ot./min | Nejrychlejší inference LLM na světě; denně se resetuje |\n\nDostupné zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Bezplatný API klíč — console.groq.com)\n\n| Úroveň | Denní limit | Limit rychlosti | Poznámky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisíc otáček za minutu** | 30 ot./min na model | Žádná kreditní karta; limit 429, neúčtováno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **💡 Ultimátní bezplatný zásobník:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> → iFlow (5 models, unlimited)\n> → Qwen (4 models, unlimited)\n> → Gemini CLI (180K/mo)\n> → Cerebras (1M tok/day)\n> → Groq (14.4K req/day)\n> → NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a už nikdy nebudete platit za umělou inteligenci.\n\n## 🎙️ Kombinovaná transkripce zdarma\n\n> Přepisujte libovolné audio/video za **0 $** – Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako záložní nástroj, Groq Whisper jako neomezená nouzová záloha.\n\n| Poskytovatel | Bezplatné kredity | Nejlepší model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| 🟢 **Deepgram** | **200 dolarů zdarma** (registrace) | `nova-3` — nejvyšší přesnost, více než 30 jazyků | Žádný limit RPM pro kredity zdarma |\n| 🔵 **AssemblyAI** | **50 dolarů zdarma** (registrace) | `universal-3-pro` — kapitoly, sentiment, osobní údaje | Žádný limit RPM pro kredity zdarma |\n| 🔴 **Groq** | **Navždy zdarma** | `whisper-large-v3` — OpenAI Šepot | 30 ot./min (omezená rychlost) |\n\n**Navrhovaná kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nPak v `/dashboard/media` → záložka **Přepis** : nahrajte libovolný zvukový nebo video soubor → vyberte kombinovaný koncový bod → získejte přepis v podporovaných formátech.\n\n## 💡 Klíčové vlastnosti\n\nOmniRoute v2.0 je navržen jako operační platforma, nikoli pouze jako proxy pro relé.\n\n### 🆕 Nové — Vylepšení inspirovaná ClawRouterem (březen 2026)\n\n| Funkce | Co to dělá |\n| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Rychlá rodina** | Modely xAI za 0,20 USD/0,50 USD/M – v benchmarku 1143 ms (o 30 % rychlejší než Gemini 2.5 Flash) |\n| 🧠 **GLM-5 přes Z.AI** | 128 tisíc výstupních dat, 0,5 USD/1 milion USD – nejnovější vlajková loď rodiny GLM |\n| 🔮 **MiniMax M2.5** | Úvaha + agentní úkoly za 0,30 USD/1 milion – významný upgrade oproti M2.1 |\n| 🎯 **Příznak volání nástroje pro každý model** | `toolCalling: true/false` v registru — AutoCombo přeskakuje modely, které nepodporují nástroje. |\n| 🌍 **Detekce vícejazyčného záměru** | Klíčová slova PT/ZH/ES/AR v bodování AutoCombo – lepší výběr modelu pro neanglický obsah |\n| 📊 **Záložní metody řízené benchmarkem** | Skutečná latence p95 z živých požadavků poskytuje kombinované skóre – AutoCombo se učí ze skutečných dat |\n| 🔁 **Požádat o deduplikaci** | Okno pro deduplikaci na základě hashování obsahu – bezpečné pro více agentů, zabraňuje duplicitním platbám |\n| 🔌 **Strategie pro zásuvné routery** | Rozšiřitelné rozhraní `RouterStrategy` – přidejte si vlastní logiku směrování jako pluginy |\n\n### 🚀 Předchozí verze v2.0.9+ — Hřiště, otisky prstů v CLI a ACP\n\n| Funkce | Co to dělá |\n| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Modelové hřiště** | Stránka řídicího panelu pro přímé testování libovolného modelu – selektory poskytovatele/modelu/koncového bodu, editor Monaco, streamování, přerušení, načasování |\n| 🔏 **Porovnávání otisků prstů v CLI** | Řazení hlaviček/těl serveru podle poskytovatele tak, aby odpovídalo nativním podpisům CLI – přepínání pro jednotlivé poskytovatele v Nastavení &gt; Zabezpečení. **Vaše IP adresa proxy serveru je zachována.** |\n| 🤝 **Podpora ACP (Agent Client Protocol)** | Vyhledávání agentů CLI (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 dalších), generátor procesů, koncový bod `/api/acp/agents` |\n| 🤖 **Řídicí panel agentů ACP** | Ladění › Stránka Agenti — mřížka 14 agentů se stavem instalace, verzí a formulářem pro vlastní agenta pro libovolný nástroj CLI. Uživatelé **OpenCode** získají tlačítko „Stáhnout opencode.json“, které automaticky vygeneruje konfiguraci připravenou k použití se všemi dostupnými modely. |\n| 🔧 **Směrování `apiFormat` pro vlastní model** | Vlastní modely s `apiFormat: \"responses\"` nyní správně směrují do překladače Responses API. |\n| 🏢 **Izolace pracovního prostoru Codexu** | Více pracovních prostorů Codexu na jeden e-mail – OAuth správně odděluje připojení podle ID pracovního prostoru |\n| 🔄 **Automatická aktualizace elektronů** | Desktopová aplikace kontroluje aktualizace + automaticky se instaluje po restartu |\n\n### 🤖 Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dělá |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **MCP Server (16 nástrojů)** | Nástroje IDE/agent prostřednictvím 3 transportů: stdio, SSE ( `/api/mcp/sse` ), Streamovatelný HTTP ( `/api/mcp/stream` ) |\n| 🤝 **A2A server (JSON-RPC + SSE)** | Spouštění úloh mezi agenty se synchronizací a streamováním |\n| 🧭 **Konsolidovaná stránka koncových bodů** | Stránka pro správu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| 🎚️ **Přepínače pro povolení/zakázání služby** | Přepínače ZAP/VYP pro MCP a A2A s trvalým nastavením (výchozí: VYP) |\n| 🛰️ **Srdeční tep za běhu MCP** | Skutečný stav procesu (pid, doba provozuschopnosti, stáří heartbeatu, transport, režim rozsahu) |\n| 📋 **Auditní záznam MCP** | Filtrovatelné protokoly auditu s hodnocením úspěchu/neúspěchu a klíčovým přiřazením |\n| 🔐 **Vynucování rozsahu MCP** | 9 podrobných oprávnění pro řízený přístup k nástrojům |\n| 📡 **Správa životního cyklu úkolů A2A** | Seznam/filtrování úloh, kontrola událostí/artefaktů, zrušení spuštěných úloh |\n| 📋 **Objevení karty agenta** | `/.well-known/agent.json` pro automatické vyhledávání klientů |\n| 🧪 **Testovací postroj Protocol E2E** | Skutečné MCP SDK + toky klientů A2A v `test:protocols:e2e` |\n| ⚙️ **Provozní kontroly** | Kombinace přepínačů, použití profilů odolnosti, resetování jističů z jednoho ovládacího panelu |\n\n### 🧠 Směrování a inteligence\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| 🎯 **Inteligentní čtyřúrovňový záložní systém** | Automatická trasa: Předplatné → API klíč → Levné → Zdarma |\n| 📊 **Sledování kvót v reálném čase** | Počet tokenů v reálném čase + odpočet resetování pro každého poskytovatele |\n| 🔄 **Překlad formátu** | OpenAI ↔ Claude ↔ Gemini ↔ Odpovědi s konverzemi bezpečnými pro schéma |\n| 👥 **Podpora více účtů** | Více účtů na poskytovatele s inteligentním výběrem |\n| 🔄 **Automatická aktualizace tokenů** | Tokeny OAuth se automaticky obnovují při opakovaném pokusu. |\n| 🎨 **Vlastní kombinace** | 6 vyvažovacích strategií + řízení záložního řetězce |\n| 🌐 **Směrovač se zástupnými znaky** | dynamické směrování `provider/*` |\n| 🧠 **Přemýšlení o rozpočtových kontrolách** | Limity pro průchozí, automatické, vlastní a adaptivní uvažování |\n| 🔀 **Aliasy modelů** | Vestavěné + vlastní aliasování modelů a bezpečnost migrace |\n| ⚡ **Degradace pozadí** | Směrujte úlohy na pozadí s nízkou prioritou na levnější modely |\n| 🧪 **Chytré směrování s ohledem na úkoly** | Automatický výběr modelu podle typu obsahu (kódování/vize/analýza/sumarizace) |\n| 💬 **Vstřikování do systému** | Globální kontroly chování uplatňované konzistentně |\n| 📄 **Kompatibilita API pro odpovědi** | Plná podpora `/v1/responses` pro Codex a pokročilé agentické pracovní postupy |\n\n### 🎵 Multimodální API\n\n| Funkce | Co to dělá |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Generování obrázků** | `/v1/images/generations` s cloudovým a lokálním backendem |\n| 📐 **Vložení** | `/v1/embeddings` pro vyhledávání a RAG pipelines |\n| 🎤 **Přepis zvuku** | `/v1/audio/transcriptions` (Whisper a další poskytovatelé) |\n| 🔊 **Převod textu na řeč** | `/v1/audio/speech` (více enginů/poskytovatelů) |\n| 🎬 **Generování videa** | `/v1/videos/generations` (pracovní postupy ComfyUI + SD WebUI) |\n| 🎵 **Hudební generace** | `/v1/music/generations` (pracovní postupy ComfyUI) |\n| 🛡️ **Moderování** | Bezpečnostní kontroly `/v1/moderations` |\n| 🔀 **Změna pořadí** | `/v1/rerank` pro hodnocení relevance |\n| 🔍 **Vyhledávání na webu** 🆕 | `/v1/search` — 5 poskytovatelů (Serper, Brave, Perplexity, Exa, Tavily), více než 6 500 zdarma/měsíc, automatické přepnutí na záložní systém, mezipaměť |\n\n### 🛡️ Odolnost, bezpečnost a správa věcí veřejných\n\n| Funkce | Co to dělá |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| 🔌 **Jističe** | Vypnutí/obnovení pro každý model s ovládáním prahových hodnot |\n| 🎯 **Modely s ohledem na koncové body** | Vlastní modely deklarují podporované koncové body + formát API |\n| 🛡️ **Stádo proti hromům** | Ochrana mutexu a semaforu při událostech opakování/rychlosti |\n| 🧠 **Sémantická + podpisová mezipaměť** | Snížení nákladů/latence díky dvěma vrstvám mezipaměti |\n| ⚡ **Žádost o idempotenci** | Okno ochrany proti duplikacím |\n| 🔒 **Falšování otisků prstů pomocí TLS** | Otisk TLS podobný prohlížeči – **snižuje detekci botů a nahlašování účtů** |\n| 🔏 **Porovnávání otisků prstů v CLI** | Shoduje se s nativními podpisy požadavků CLI – **snižuje riziko zablokování a zároveň zachovává IP adresu proxy** |\n| 🌐 **Filtrování IP adres** | Ovládání seznamu povolených/blokovaných položek pro odhalená nasazení |\n| 📊 **Upravitelné limity rychlosti** | Konfigurovatelné globální/na úrovni poskytovatele limity s perzistencí |\n| 🔑 **Správa klíčů API a stanovení rozsahu** | Bezpečné vydávání/rotace klíčů a kontroly modelu/poskytovatele |\n| 🛡️ **Chráněné `/models`** | Volitelné ověřování a skrytí poskytovatele pro katalog modelů |\n\n### 📊 Pozorovatelnost a analytika\n\n| Funkce | Co to dělá |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| 📝 **Žádost + protokolování proxy** | Úplné protokolování požadavků/odpovědí a proxy |\n| 📋 **Sjednocený panel protokolů** | Zobrazení požadavků, proxy, auditu a konzole na jedné stránce |\n| 🔍 **Vyžádat si telemetrii** | Latence p50/p95/p99 a trasování požadavků |\n| 🏥 **Panel zdraví** | Doba provozuschopnosti, stavy jističů, uzamčení, statistiky mezipaměti |\n| 💰 **Sledování nákladů** | Kontrola rozpočtu a přehled o cenách pro jednotlivé modely |\n| 📈 **Analytické vizualizace** | Přehledy využití modelů/poskytovatelů a zobrazení trendů |\n| 🧪 **Rámec hodnocení** | Testování zlaté sady s konfigurovatelnými strategiemi shody |\n\n### ☁️ Nasazení a platforma\n\n| Funkce | Co to dělá |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| 🌐 **Nasazení kdekoli** | Localhost, VPS, Docker, cloudová prostředí |\n| 💾 **Synchronizace s cloudem** | Synchronizace konfigurace přes cloud worker |\n| 🔄 **Zálohování/Obnovení** | Toky exportu/importu a obnovy po havárii |\n| 🧙 **Průvodce nástupem** | Průvodce prvním spuštěním |\n| 🔧 **Panel nástrojů CLI** | Nastavení oblíbených kódovacích nástrojů jedním kliknutím |\n| 🎮 **Modelové hřiště** | Otestujte libovolného poskytovatele/model/koncový bod z řídicího panelu |\n| 🔏 **Přepínač otisků prstů v příkazovém řádku** | Porovnávání otisků prstů podle poskytovatele v Nastavení &gt; Zabezpečení |\n| 🌐 **i18n (30 jazyků)** | Plná jazyková podpora dashboardu a dokumentace s psaním zprava doleva |\n| 📂 **Adresář vlastních dat** | Přepsání `DATA_DIR` pro umístění úložiště |\n\n### Hluboký pohled na funkce\n\n#### Chytrá záložní funkce s praktickou kontrolou nákladů\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyž selže kvóta, rychlost nebo stav, OmniRoute automaticky přejde k dalšímu kandidátovi bez nutnosti ručního přepínání.\n\n#### Správa protokolů, která je viditelná a ovladatelná\n\n- MCP + A2A jsou viditelné v uživatelském rozhraní a dokumentaci (nejsou skryté)\n- API pro stav protokolu zpřístupňují živá provozní data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnují akce pro operace 2. dne (přepínání kombinací, resetování jističů, zrušení úkolů)\n\n#### Pracovní postup překladatele + validace\n\nOblast překladatele zahrnuje:\n\n- **Hřiště** : kontroly transformace požadavků\n- **Tester chatu** : kompletní okružní cesta požadavku/odpovědi\n- **Testovací stolice** : více případů v jednom běhu\n- **Živý monitor** : zobrazení provozu v reálném čase\n\nPlus validace protokolu se skutečnými klienty pomocí `npm run test:protocols:e2e` .\n\n> 📖 **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** — Referenční informace o nástrojích, konfigurace IDE a příklady klientů\n>\n> 📖 **[Soubor README pro A2A Server](src/lib/a2a/README.md)** — Dovednosti, metody JSON-RPC, streamování a životní cyklus úloh\n\n## 🧪 Hodnocení (Evals)\n\nOmniRoute obsahuje vestavěný hodnotící rámec pro testování kvality odpovědí LLM v porovnání se zlatou sadou. Přístup k němu je možný přes **Analýzy → Hodnocení** v dashboardu.\n\n### Vestavěná zlatá sada\n\nPředinstalovaná sada „OmniRoute Golden Set“ obsahuje testovací případy pro:\n\n- Zdravím, matematika, zeměpis, generování kódu\n- Shoda s formátem JSON, překlad, generování markdownů\n- Bezpečnostní odmítnutí (škodlivý obsah), počítání, booleovská logika\n\n### Strategie hodnocení\n\n| Strategie | Popis | Příklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Výstup se musí přesně shodovat | `\"4\"` |\n| `contains` | Výstup musí obsahovat podřetězec (bez rozlišení velkých a malých písmen) | `\"Paris\"` |\n| `regex` | Výstup musí odpovídat vzoru regulárních výrazů | `\"1.*2.*3\"` |\n| `custom` | Vlastní JS funkce vrací true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Průvodce nastavením\n\n### Nastavení protokolu (MCP + A2A)\n\n<details>\n<summary><b>🧩 Nastavení MCP (Model Context Protocol)</b></summary>\n</details>\n\nSpuštění MCP transportu v režimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporučený postup ověření:\n\n1. Připojte svého MCP klienta přes stdio.\n2. Spusťte `omniroute_get_health` .\n3. Spusťte `omniroute_list_combos` .\n4. Otevřete `/dashboard/mcp` pro ověření prezenčního signálu, aktivity a auditu.\n\nUžitečná API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n<details>\n<summary><b>🤝 Nastavení A2A (Agent2Agent)</b></summary>\n</details>\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat úkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSpráva životního cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvozní uživatelské rozhraní:\n\n- `/dashboard/a2a` pro pozorovatelnost úloh/stavů/streamů a akce kouření\n\n<details>\n<summary><b>🧪 Komplexní validace protokolu</b></summary>\n</details>\n\nOvěřte oba protokoly se skutečnými klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTím se ověřuje:\n\n- Připojení/seznam/volání klienta MCP SDK\n- A2A objevování/odesílání/streamování/získávání/zrušení\n- Křížová kontrola dat v auditu MCP a API pro správu úloh A2A\n\n<details>\n<summary><b>💳 Poskytovatelé předplatného</b></summary>\n</details>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionály:** Pro složité úkoly používejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvótu pro každý model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Správa limitů účtu Codex (5h + týdně)\n\nKaždý účet Codex má nyní přepínače zásad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinového prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zásadu týdenního prahu okna.\n- Prahové chování: když povolené okno dosáhne využití &gt;=90 %, je daný účet přeskočen.\n- Chování rotace: OmniRoute automaticky přesměruje na další způsobilý účet Codex.\n- Chování při resetování: Po `resetAt` určité doby se účet automaticky opět stane způsobilým.\n\nScénáře:\n\n- `5h ON` + `Weekly ON` : účet je přeskočen, když kterékoli z oken dosáhne prahové hodnoty.\n- `5h OFF` + `Weekly ON` : účet může být zablokován pouze týdenním používáním.\n- `5h ON` + `Weekly OFF` : účet může být zablokován pouze při 5hodinovém používání.\n- `resetAt` passed: účet se automaticky znovu zapne (bez ručního opětovného povolení).\n\n### Gemini CLI (ZDARMA 180 000/měsíc!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepší hodnota:** Obrovská bezplatná úroveň! Použijte ji před placenými úrovněmi.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n<details>\n<summary><b>🔑 Poskytovatelé klíčů API</b></summary>\n</details>\n\n### NVIDIA NIM (BEZPLATNÝ přístup pro vývojáře — více než 70 modelů)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Získejte zdarma klíč API (včetně 1000 inferenčních kreditů)\n3. Ovládací panel → Přidat poskytovatele → NVIDIA NIM:\n - Klíč API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a více než 50 dalších\n\n**Tip pro profesionály:** API kompatibilní s OpenAI – funguje bez problémů s překladem formátů OmniRoute!\n\n### Hluboké vyhledávání\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatná úroveň!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Získejte klíč API (včetně bezplatné úrovně)\n3. Ovládací panel → Přidat poskytovatele → Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionály:** Ultrarychlá inference – nejlepší pro kódování v reálném čase!\n\n### OpenRouter (100+ modelů)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Získat klíč API\n3. Ovládací panel → Přidat poskytovatele → OpenRouter\n\n**Modely:** Získejte přístup k více než 100 modelům od všech hlavních poskytovatelů prostřednictvím jediného klíče API.\n\n<details>\n<summary><b>💰 Levní poskytovatelé (záložní)</b></summary>\n</details>\n\n### GLM-4.7 (Denní reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Získejte klíč API z kódovacího plánu\n3. Nástěnka → Přidat klíč API:\n - Poskytovatel: `glm`\n - Klíč API: `your-key`\n\n**Použití:** `glm/glm-4.7`\n\n**Tip pro profesionály:** Programovací plán nabízí 3× kvótu za cenu 1/7! Obnovuje se denně v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionály:** Nejlevnější varianta pro dlouhý kontext (1 milion tokenů)!\n\n### Kimi K2 (paušální poplatek 9 dolarů měsíčně)\n\n1. Odebírat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Získat klíč API\n3. Nástěnka → Přidat klíč API\n\n**Použití:** `kimi/kimi-latest`\n\n**Tip pro profesionály:** Fixních 9 $/měsíc za 10 milionů tokenů = efektivní náklady 0,90 $/1 milion!\n\n<details>\n<summary><b>🆓 BEZPLATNÍ poskytovatelé (nouzové zálohování)</b></summary>\n</details>\n\n### iFlow (5 BEZPLATNÝCH modelů přes OAuth)\n\n```bash\nDashboard → Connect iFlow\n→ iFlow OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kódem zařízení)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n<details>\n<summary><b>🎨 Vytvořte kombinace</b></summary>\n</details>\n\n### Příklad 1: Maximalizace předplatného → Levné zálohování\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Příklad 2: Pouze zdarma (nulové náklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n<details>\n<summary><b>🔧 Integrace s rozhraním příkazového řádku</b></summary>\n</details>\n\n### IDE kurzoru\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jedním kliknutím použijte stránku **Nástroje CLI** na řídicím panelu nebo ručně upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Možnost 1 – Dashboard (doporučeno):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Možnost 2 – Manuální úprava:** Úprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznámka:** OpenClaw funguje pouze s lokálním OmniRoute. Místo `localhost` použijte `127.0.0.1` , abyste se vyhnuli problémům s rozlišením IPv6.\n\n### Cline / Pokračovat / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Přidání OmniRoute jako vlastního poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvořte/upravte `opencode.json` v kořenovém adresáři projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` přidejte jakýkoli model dostupný ve vašem koncovém bodu OmniRoute `/v1/models` . Použijte formát `provider/model-id` z vašeho dashboardu OmniRoute.\n\n---\n\n## 🐛 Řešení problémů\n\n<details>\n<summary><b>Kliknutím rozbalíte průvodce řešením problémů</b></summary>\n</details>\n\n**\"Jazykový model neposkytoval zprávy\"**\n\n- Kvóta poskytovatele vyčerpána → Zkontrolujte sledování kvót na řídicím panelu\n- Řešení: Použijte záložní kombinovanou variantu nebo přejděte na levnější úroveň\n\n**Omezení rychlosti**\n\n- Kvóta předplatného vyčerpána → Přechod na GLM/MiniMax\n- Přidat kombo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vypršela**\n\n- Automaticky aktualizováno službou OmniRoute\n- Pokud problémy přetrvávají: Ovládací panel → Poskytovatel → Znovu připojit\n\n**Vysoké náklady**\n\n- Zkontrolujte statistiky využití v sekci Nástěnka → Náklady\n- Přepnout primární model na GLM/MiniMax\n- Pro nekritické úlohy použijte bezplatnou úroveň (Gemini CLI, iFlow).\n\n**Porty řídicího panelu/API jsou nesprávné**\n\n- `PORT` je kanonický základní port (a standardně port API)\n- `API_PORT` přepisuje pouze posluchač API kompatibilní s OpenAI.\n- `DASHBOARD_PORT` přepisuje pouze posluchač dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaši veřejnou URL adresu řídicího panelu (pro zpětná volání OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ověřte, zda `BASE_URL` odkazuje na vaši spuštěnou instanci.\n- Ověřte, zda `CLOUD_URL` odkazuje na váš očekávaný cloudový koncový bod.\n- Udržujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na straně serveru.\n\n**První přihlášení nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud není nastaveno, záložní heslo je `123456`\n\n**Žádné protokoly požadavků**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test připojení ukazuje „Neplatné“ pro poskytovatele kompatibilní s OpenAI**\n\n- Mnoho poskytovatelů nezpřístupňuje koncový bod `/models`\n- OmniRoute v1.0.6+ zahrnuje záložní ověření pomocí dokončení chatu\n- Zajistěte, aby základní URL adresa obsahovala příponu `/v1`\n\n### 🔐 OAuth na vzdáleném serveru\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Důležité pro uživatele, kteří provozují OmniRoute na VPS, Dockeru nebo jakémkoli vzdáleném serveru**\n\n#### Proč selhává OAuth v rozhraní CLI Antigravity / Gemini na vzdálených serverech?\n\nPoskytovatelé rozhraní CLI **Antigravity** a **Gemini** používají **Google OAuth 2.0** . Google vyžaduje, aby se `redirect_uri` v toku OAuth přesně shodoval s jedním z předregistrovaných URI v konzoli Google Cloud Console aplikace.\n\nPřihlašovací údaje OAuth, které jsou součástí OmniRoute, jsou registrovány **pouze pro `localhost`** . Když přistupujete k OmniRoute na vzdáleném serveru (např. `https://omniroute.myserver.com` ), Google odmítne ověření pomocí:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Řešení: Nakonfigurujte si vlastní přihlašovací údaje OAuth\n\nV Google Cloud Console je potřeba vytvořit **ID klienta OAuth 2.0** s URI vašeho serveru.\n\n#### Krok za krokem\n\n**1. Otevřete konzoli Google Cloud**\n\nPřejděte na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvořte nové ID klienta OAuth 2.0**\n\n- Klikněte na **„+ Vytvořit přihlašovací údaje“** → **„ID klienta OAuth“**\n- Typ aplikace: **„Webová aplikace“**\n- Název: cokoli chcete (např. `OmniRoute Remote` )\n\n**3. Přidejte autorizované URI pro přesměrování**\n\nDo pole **„Autorizované identifikátory URI pro přesměrování“** přidejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraďte `your-server.com` doménou nebo IP adresou vašeho serveru (v případě potřeby uveďte i port, např. `http://45.33.32.156:20128/callback` ).\n\n**4. Uložte a zkopírujte přihlašovací údaje**\n\nPo vytvoření Google zobrazí **ID klienta** a **tajný kód klienta** .\n\n**5. Nastavení proměnných prostředí**\n\nVe vašem souboru `.env` (nebo proměnných prostředí Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu připojit**\n\nŘídicí panel → Poskytovatelé → Antigravity (nebo Gemini CLI) → OAuth\n\nGoogle nyní bude správně přesměrovávat na `https://your-server.com/callback` .\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nPokud si teď nechcete nastavovat vlastní přihlašovací údaje, můžete stále použít **ruční postup pro URL** :\n\n1. OmniRoute otevírá autorizační URL od Googlu\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru).\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče (i když se stránka nenačte)\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute.\n5. Klikněte na **„Připojit“**\n\n> To funguje, protože autorizační kód v URL adrese je platný bez ohledu na to, zda se načetla přesměrovací stránka.\n\n---\n\n#### Dočasné řešení (bez vlastních přihlašovacích údajů)\n\nChcete-li získat přístup k přihlašovacím údajům bez vlastní konfigurace, můžete použít následující postup:\n\n1. OmniRoute otevře URL autorizace Google\n2. Po autorizaci se Google pokusí přesměrovat na `localhost` (což selže na vzdáleném serveru)\n3. **Zkopírujte celou URL adresu** z adresního řádku prohlížeče\n4. Vložte tuto URL adresu do pole zobrazeného v modálním okně připojení OmniRoute\n5. Klikněte na **„Připojit\"**\n\n> Toto řešení funguje, protože autorizační kód v URL adrese je platný bez ohledu na načtení přesměrovací stránky.\n\n---\n\n## 🛠️ Technologický stack\n\n<details>\n<summary><b>Kliknutím rozbalíte podrobnosti o technologickém stacku</b></summary>\n</details>\n\n- **Runtime** : Node.js 18–22 LTS (⚠️ Node.js 24+ **není podporován** — nativní binární soubory `better-sqlite3` jsou nekompatibilní)\n- **Jazyk** : TypeScript 5.9 — **100% TypeScript** napříč `src/` a `open-sse/` ( `any` v základních modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databáze** : LowDB (JSON) + SQLite (stav domény + protokoly proxy + audit MCP + rozhodnutí o směrování)\n- **Schémata** : Zod (validace I/O nástrojů MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamování** : Události odeslané serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klíče + autorizace s rozsahem MCP\n- **Testování** : Node.js test runner + Vitest (900+ testů včetně unit, integračních, E2E)\n- **CI/CD** : Akce GitHubu (automatické publikování v npm + Docker Hub při vydání)\n- **Webová stránka** : [omniroute.online](https://omniroute.online)\n- **Balíček** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistič, exponenciální odstavení, ochrana proti hromům, falešné TLS, automatické kombinované samoopravování\n\n---\n\n## 📖 Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uživatelská příručka](docs/USER_GUIDE.md) | Poskytovatelé, kombinace, integrace CLI, nasazení |\n| [Referenční informace k API](docs/API_REFERENCE.md) | Všechny koncové body s příklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nástrojů MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamování, správa úloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorové bodování, balíčky režimů, samoléčba |\n| [Odstraňování problémů](docs/TROUBLESHOOTING.md) | Běžné problémy a jejich řešení |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a interní prvky systému |\n| [Přispívání](CONTRIBUTING.md) | Nastavení a pokyny pro vývoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpečnostní zásady](SECURITY.md) | Hlášení zranitelností a bezpečnostní postupy |\n| [Nasazení virtuálního počítače](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletní průvodce: Nastavení virtuálního počítače + nginx + Cloudflare |\n| [Galerie funkcí](docs/FEATURES.md) | Vizuální prohlídka řídicího panelu se snímky obrazovky |\n| [Kontrolní seznam vydání](docs/RELEASE_CHECKLIST.md) | Kroky ověření před vydáním |\n\n---\n\n## 🗺️ Plán\n\nOmniRoute má **v plánu více než 210 funkcí** v několika fázích vývoje. Zde jsou klíčové oblasti:\n\n| Kategorie | Plánované funkce | Hlavní body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| 🧠 **Směrování a inteligence** | 25+ | Směrování s nejnižší latencí, směrování založené na tagech, kontrola kvót před výstupem, výběr účtu P2C |\n| 🔒 **Zabezpečení a dodržování předpisů** | 20+ | Zpevnění SSRF, maskování přihlašovacích údajů, limit rychlosti pro každý koncový bod, stanovení rozsahu klíčů pro správu |\n| 📊 **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledování kvót v reálném čase, sledování nákladů podle modelu |\n| 🔄 **Integrace poskytovatelů** | 20+ | Dynamický registr modelů, doba zchlazení poskytovatelů, Codex pro více účtů, analýza kvót Copilota |\n| ⚡ **Výkon** | 15+ | Dvojitá vrstva mezipaměti, mezipaměť výzev, mezipaměť odpovědí, udržování streamování, dávkové API |\n| 🌐 **Ekosystém** | 10+ | WebSocket API, horké opětovné načítání konfigurace, distribuované úložiště konfigurace, komerční režim |\n\n### 🔜 Již brzy\n\n- 🔗 **Integrace OpenCode** — Nativní podpora poskytovatelů pro IDE kódování s AI v OpenCode\n- 🔗 **Integrace TRAE** — Plná podpora vývojového rámce TRAE pro umělou inteligenci\n- 📦 **Dávkové API** — Asynchronní dávkové zpracování hromadných požadavků\n- 🎯 **Směrování na základě tagů** — Směrování požadavků na základě vlastních tagů a metadat\n- 💰 **Strategie nejnižších nákladů** – Automaticky vybere nejlevnějšího dostupného poskytovatele\n\n> 📝 Úplné specifikace funkcí jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobných specifikací)\n\n---\n\n## 👥 Přispěvatelé\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Přispěvatelé](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak přispět\n\n1. Vytvoření forku repozitáře\n2. Vytvořte si vlastní větev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrďte změny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do větve ( `git push origin feature/amazing-feature` )\n5. Otevřít žádost o změny (pull request)\n\nPodrobné pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydání nové verze\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Hvězdná historie\n\n## Hvězdáři v průběhu času\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvězdáři v průběhu času](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## 🙏 Poděkování\n\nZvláštní poděkování patří **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** – původnímu projektu, který inspiroval tento fork. OmniRoute staví na tomto neuvěřitelném základu s dalšími funkcemi, multimodálními API a kompletním přepsáním TypeScriptu.\n\nZvláštní poděkování patří **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – původní implementaci Go, která inspirovala tento JavaScriptový port.\n\n---\n\n## 📄 Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n<div align=\"center\">\n <sub>Vytvořeno s ❤️ pro vývojáře, kteří programují 24 hodin denně, 7 dní v týdnu</sub>\n <br>\n <sub><p data-md-type=\"paragraph\"><a href=\"https://omniroute.online\">omniroute.online</a></p></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}}, "docs/i18n/ms/docs/guides/USER_GUIDE.md": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785746499.9295108, "n": 37587, "h": "3e844b7e135eddd1", "c": "# User Guide (Bahasa Melayu)\n\n🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/USER_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/USER_GUIDE.md) · 🇮🇳 [te](../../te/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## 🎯 Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## 📖 Provider Setup\n\n### 🔐 Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### 💰 Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### 🆓 FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard → Connect Qoder → OAuth login → Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard → Connect Qwen → Device code auth → Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## 🎨 Combos\n\nYou can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## 🔧 CLI Integration\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Penempatan\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.\n\n<details>\n<summary><b>View xbps-src template</b></summary>\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## 📊 Available Models\n\n<details>\n<summary><b>View all available models</b></summary>\n\n**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n</details>\n\n---\n\n## 🧩 Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers → [Provider] → Custom Models**.\n\nNotes:\n\n- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard → Settings → Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* → Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard → Settings → Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** — System-level request shaping:\n - **Requests Per Minute (RPM)** — Maximum requests per minute per account\n - **Min Time Between Requests** — Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** — Maximum simultaneous requests per account\n\n2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** — Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** — Consecutive provider failures before opening the breaker\n - **Reset Timeout** — Time window before the provider is tested again\n - **CLOSED** (Healthy) — Requests flow normally\n - **OPEN** — Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** — Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard → Health** only.\n\n4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard → Settings → System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all → share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard → Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard → Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## 🖥️ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Pasang\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput → `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |\n\n📖 Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "7c23dab64de929686d2326f6824527ba9c746ca9": {"t": 1785764412.907156, "n": 37587, "h": "3e844b7e135eddd1", "c": "# User Guide (Bahasa Melayu)\n\n🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/USER_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/USER_GUIDE.md) · 🇮🇳 [te](../../te/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## 🎯 Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## 📖 Provider Setup\n\n### 🔐 Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### 💰 Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### 🆓 FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard → Connect Qoder → OAuth login → Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard → Connect Qwen → Device code auth → Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## 🎨 Combos\n\nYou can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## 🔧 CLI Integration\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Penempatan\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.\n\n<details>\n<summary><b>View xbps-src template</b></summary>\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## 📊 Available Models\n\n<details>\n<summary><b>View all available models</b></summary>\n\n**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n</details>\n\n---\n\n## 🧩 Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers → [Provider] → Custom Models**.\n\nNotes:\n\n- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard → Settings → Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* → Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard → Settings → Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** — System-level request shaping:\n - **Requests Per Minute (RPM)** — Maximum requests per minute per account\n - **Min Time Between Requests** — Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** — Maximum simultaneous requests per account\n\n2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** — Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** — Consecutive provider failures before opening the breaker\n - **Reset Timeout** — Time window before the provider is tested again\n - **CLOSED** (Healthy) — Requests flow normally\n - **OPEN** — Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** — Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard → Health** only.\n\n4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard → Settings → System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all → share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard → Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard → Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## 🖥️ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Pasang\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput → `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |\n\n📖 Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "8a1d9beb55fe825bd132c8696117046258869a79": {"t": 1785764414.580887, "n": 38219, "h": "c4764e7caf2c0a15", "c": "# User Guide (Bahasa Melayu)\n\n🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/USER_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/USER_GUIDE.md) · 🇮🇳 [te](../../te/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!\n\n---\n\n## 🎯 Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash (180K free/month)\n 2. if/kimi-k2-thinking (unlimited free)\n 3. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## 📖 Provider Setup\n\n### 🔐 Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n#### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### 💰 Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### 🆓 FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard → Connect Qoder → OAuth login → Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard → Connect Qwen → Device code auth → Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## 🎨 Combos\n\nYou can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## 🔧 CLI Integration\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Penempatan\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.\n\n<details>\n<summary><b>View xbps-src template</b></summary>\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## 📊 Available Models\n\n<details>\n<summary><b>View all available models</b></summary>\n\n**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n</details>\n\n---\n\n## 🧩 Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers → [Provider] → Custom Models**.\n\nNotes:\n\n- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard → Settings → Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* → Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard → Settings → Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** — System-level request shaping:\n - **Requests Per Minute (RPM)** — Maximum requests per minute per account\n - **Min Time Between Requests** — Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** — Maximum simultaneous requests per account\n\n2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** — Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** — Consecutive provider failures before opening the breaker\n - **Reset Timeout** — Time window before the provider is tested again\n - **CLOSED** (Healthy) — Requests flow normally\n - **OPEN** — Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** — Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard → Health** only.\n\n4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard → Settings → System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all → share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard → Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard → Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## 🖥️ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Pasang\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput → `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |\n\n📖 Full documentation: [`electron/README.md`](../electron/README.md)\n"}}, "docs/i18n/no/docs/guides/USER_GUIDE.md": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785746502.1201484, "n": 37581, "h": "2b2b21e44f8ea8ff", "c": "# User Guide (Norsk)\n\n🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/USER_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/USER_GUIDE.md) · 🇮🇳 [te](../../te/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## 🎯 Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## 📖 Provider Setup\n\n### 🔐 Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### 💰 Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### 🆓 FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard → Connect Qoder → OAuth login → Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard → Connect Qwen → Device code auth → Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## 🎨 Combos\n\nYou can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## 🔧 CLI Integration\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Utrulling\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.\n\n<details>\n<summary><b>View xbps-src template</b></summary>\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## 📊 Available Models\n\n<details>\n<summary><b>View all available models</b></summary>\n\n**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n</details>\n\n---\n\n## 🧩 Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers → [Provider] → Custom Models**.\n\nNotes:\n\n- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard → Settings → Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* → Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard → Settings → Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** — System-level request shaping:\n - **Requests Per Minute (RPM)** — Maximum requests per minute per account\n - **Min Time Between Requests** — Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** — Maximum simultaneous requests per account\n\n2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** — Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** — Consecutive provider failures before opening the breaker\n - **Reset Timeout** — Time window before the provider is tested again\n - **CLOSED** (Healthy) — Requests flow normally\n - **OPEN** — Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** — Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard → Health** only.\n\n4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard → Settings → System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all → share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard → Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard → Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## 🖥️ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Installer\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput → `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |\n\n📖 Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "7c23dab64de929686d2326f6824527ba9c746ca9": {"t": 1785764413.2452216, "n": 37581, "h": "2b2b21e44f8ea8ff", "c": "# User Guide (Norsk)\n\n🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/USER_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/USER_GUIDE.md) · 🇮🇳 [te](../../te/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## 🎯 Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## 📖 Provider Setup\n\n### 🔐 Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### 💰 Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### 🆓 FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard → Connect Qoder → OAuth login → Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard → Connect Qwen → Device code auth → Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## 🎨 Combos\n\nYou can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## 🔧 CLI Integration\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Utrulling\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.\n\n<details>\n<summary><b>View xbps-src template</b></summary>\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## 📊 Available Models\n\n<details>\n<summary><b>View all available models</b></summary>\n\n**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n</details>\n\n---\n\n## 🧩 Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers → [Provider] → Custom Models**.\n\nNotes:\n\n- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard → Settings → Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* → Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard → Settings → Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** — System-level request shaping:\n - **Requests Per Minute (RPM)** — Maximum requests per minute per account\n - **Min Time Between Requests** — Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** — Maximum simultaneous requests per account\n\n2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** — Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** — Consecutive provider failures before opening the breaker\n - **Reset Timeout** — Time window before the provider is tested again\n - **CLOSED** (Healthy) — Requests flow normally\n - **OPEN** — Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** — Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard → Health** only.\n\n4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard → Settings → System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all → share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard → Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard → Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## 🖥️ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Installer\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput → `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |\n\n📖 Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "8a1d9beb55fe825bd132c8696117046258869a79": {"t": 1785764414.7922587, "n": 38213, "h": "69a5b1611104b49e", "c": "# User Guide (Norsk)\n\n🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/USER_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/USER_GUIDE.md) · 🇮🇳 [te](../../te/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!\n\n---\n\n## 🎯 Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash (180K free/month)\n 2. if/kimi-k2-thinking (unlimited free)\n 3. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## 📖 Provider Setup\n\n### 🔐 Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n#### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### 💰 Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### 🆓 FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard → Connect Qoder → OAuth login → Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard → Connect Qwen → Device code auth → Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## 🎨 Combos\n\nYou can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## 🔧 CLI Integration\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Utrulling\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.\n\n<details>\n<summary><b>View xbps-src template</b></summary>\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## 📊 Available Models\n\n<details>\n<summary><b>View all available models</b></summary>\n\n**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n</details>\n\n---\n\n## 🧩 Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers → [Provider] → Custom Models**.\n\nNotes:\n\n- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard → Settings → Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* → Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard → Settings → Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** — System-level request shaping:\n - **Requests Per Minute (RPM)** — Maximum requests per minute per account\n - **Min Time Between Requests** — Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** — Maximum simultaneous requests per account\n\n2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** — Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** — Consecutive provider failures before opening the breaker\n - **Reset Timeout** — Time window before the provider is tested again\n - **CLOSED** (Healthy) — Requests flow normally\n - **OPEN** — Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** — Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard → Health** only.\n\n4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard → Settings → System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all → share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard → Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard → Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## 🖥️ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Installer\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput → `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |\n\n📖 Full documentation: [`electron/README.md`](../electron/README.md)\n"}}, "docs/i18n/he/docs/guides/USER_GUIDE.md": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785746509.7690573, "n": 37573, "h": "a98fc610b5fc1ee4", "c": "# User Guide (עברית)\n\n🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/USER_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/USER_GUIDE.md) · 🇮🇳 [te](../../te/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## 🎯 Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## 📖 Provider Setup\n\n### 🔐 Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### 💰 Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### 🆓 FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard → Connect Qoder → OAuth login → Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard → Connect Qwen → Device code auth → Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## 🎨 Combos\n\nYou can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## 🔧 CLI Integration\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## פריסה\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.\n\n<details>\n<summary><b>View xbps-src template</b></summary>\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## 📊 Available Models\n\n<details>\n<summary><b>View all available models</b></summary>\n\n**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n</details>\n\n---\n\n## 🧩 Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers → [Provider] → Custom Models**.\n\nNotes:\n\n- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard → Settings → Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* → Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard → Settings → Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** — System-level request shaping:\n - **Requests Per Minute (RPM)** — Maximum requests per minute per account\n - **Min Time Between Requests** — Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** — Maximum simultaneous requests per account\n\n2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** — Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** — Consecutive provider failures before opening the breaker\n - **Reset Timeout** — Time window before the provider is tested again\n - **CLOSED** (Healthy) — Requests flow normally\n - **OPEN** — Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** — Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard → Health** only.\n\n4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard → Settings → System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all → share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard → Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard → Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## 🖥️ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### התקנה\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput → `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |\n\n📖 Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "7c23dab64de929686d2326f6824527ba9c746ca9": {"t": 1785764410.926768, "n": 37573, "h": "a98fc610b5fc1ee4", "c": "# User Guide (עברית)\n\n🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/USER_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/USER_GUIDE.md) · 🇮🇳 [te](../../te/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## 🎯 Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## 📖 Provider Setup\n\n### 🔐 Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### 💰 Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### 🆓 FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard → Connect Qoder → OAuth login → Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard → Connect Qwen → Device code auth → Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## 🎨 Combos\n\nYou can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## 🔧 CLI Integration\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## פריסה\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.\n\n<details>\n<summary><b>View xbps-src template</b></summary>\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## 📊 Available Models\n\n<details>\n<summary><b>View all available models</b></summary>\n\n**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n</details>\n\n---\n\n## 🧩 Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers → [Provider] → Custom Models**.\n\nNotes:\n\n- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard → Settings → Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* → Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard → Settings → Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** — System-level request shaping:\n - **Requests Per Minute (RPM)** — Maximum requests per minute per account\n - **Min Time Between Requests** — Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** — Maximum simultaneous requests per account\n\n2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** — Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** — Consecutive provider failures before opening the breaker\n - **Reset Timeout** — Time window before the provider is tested again\n - **CLOSED** (Healthy) — Requests flow normally\n - **OPEN** — Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** — Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard → Health** only.\n\n4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard → Settings → System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all → share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard → Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard → Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## 🖥️ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### התקנה\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput → `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |\n\n📖 Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "8a1d9beb55fe825bd132c8696117046258869a79": {"t": 1785764413.4347286, "n": 38205, "h": "365a9a21800e3cc7", "c": "# User Guide (עברית)\n\n🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/USER_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/USER_GUIDE.md) · 🇮🇳 [te](../../te/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!\n\n---\n\n## 🎯 Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash (180K free/month)\n 2. if/kimi-k2-thinking (unlimited free)\n 3. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## 📖 Provider Setup\n\n### 🔐 Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n#### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### 💰 Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key → Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### 🆓 FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard → Connect Qoder → OAuth login → Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard → Connect Qwen → Device code auth → Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## 🎨 Combos\n\nYou can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## 🔧 CLI Integration\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## פריסה\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.\n\n<details>\n<summary><b>View xbps-src template</b></summary>\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## 📊 Available Models\n\n<details>\n<summary><b>View all available models</b></summary>\n\n**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n</details>\n\n---\n\n## 🧩 Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers → [Provider] → Custom Models**.\n\nNotes:\n\n- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard → Settings → Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* → Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard → Settings → Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** — System-level request shaping:\n - **Requests Per Minute (RPM)** — Maximum requests per minute per account\n - **Min Time Between Requests** — Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** — Maximum simultaneous requests per account\n\n2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** — Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** — Consecutive provider failures before opening the breaker\n - **Reset Timeout** — Time window before the provider is tested again\n - **CLOSED** (Healthy) — Requests flow normally\n - **OPEN** — Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** — Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard → Health** only.\n\n4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard → Settings → System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all → share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard → Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard → Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## 🖥️ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### התקנה\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput → `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |\n\n📖 Full documentation: [`electron/README.md`](../electron/README.md)\n"}}, "docs/i18n/no/docs/reference/CLI-TOOLS.md": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785747209.9274452, "n": 13216, "h": "2c6b46e0ca45ef6d", "c": "# CLI Tools Setup Guide — OmniRoute (Norsk)\n\n🌐 **Languages:** 🇺🇸 [English](../../../../docs/CLI-TOOLS.md) · 🇸🇦 [ar](../../ar/docs/CLI-TOOLS.md) · 🇧🇬 [bg](../../bg/docs/CLI-TOOLS.md) · 🇧🇩 [bn](../../bn/docs/CLI-TOOLS.md) · 🇨🇿 [cs](../../cs/docs/CLI-TOOLS.md) · 🇩🇰 [da](../../da/docs/CLI-TOOLS.md) · 🇩🇪 [de](../../de/docs/CLI-TOOLS.md) · 🇪🇸 [es](../../es/docs/CLI-TOOLS.md) · 🇮🇷 [fa](../../fa/docs/CLI-TOOLS.md) · 🇫🇮 [fi](../../fi/docs/CLI-TOOLS.md) · 🇫🇷 [fr](../../fr/docs/CLI-TOOLS.md) · 🇮🇳 [gu](../../gu/docs/CLI-TOOLS.md) · 🇮🇱 [he](../../he/docs/CLI-TOOLS.md) · 🇮🇳 [hi](../../hi/docs/CLI-TOOLS.md) · 🇭🇺 [hu](../../hu/docs/CLI-TOOLS.md) · 🇮🇩 [id](../../id/docs/CLI-TOOLS.md) · 🇮🇹 [it](../../it/docs/CLI-TOOLS.md) · 🇯🇵 [ja](../../ja/docs/CLI-TOOLS.md) · 🇰🇷 [ko](../../ko/docs/CLI-TOOLS.md) · 🇮🇳 [mr](../../mr/docs/CLI-TOOLS.md) · 🇲🇾 [ms](../../ms/docs/CLI-TOOLS.md) · 🇳🇱 [nl](../../nl/docs/CLI-TOOLS.md) · 🇳🇴 [no](../../no/docs/CLI-TOOLS.md) · 🇵🇭 [phi](../../phi/docs/CLI-TOOLS.md) · 🇵🇱 [pl](../../pl/docs/CLI-TOOLS.md) · 🇵🇹 [pt](../../pt/docs/CLI-TOOLS.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) · 🇷🇴 [ro](../../ro/docs/CLI-TOOLS.md) · 🇷🇺 [ru](../../ru/docs/CLI-TOOLS.md) · 🇸🇰 [sk](../../sk/docs/CLI-TOOLS.md) · 🇸🇪 [sv](../../sv/docs/CLI-TOOLS.md) · 🇰🇪 [sw](../../sw/docs/CLI-TOOLS.md) · 🇮🇳 [ta](../../ta/docs/CLI-TOOLS.md) · 🇮🇳 [te](../../te/docs/CLI-TOOLS.md) · 🇹🇭 [th](../../th/docs/CLI-TOOLS.md) · 🇹🇷 [tr](../../tr/docs/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) · 🇵🇰 [ur](../../ur/docs/CLI-TOOLS.md) · 🇻🇳 [vi](../../vi/docs/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/CLI-TOOLS.md)\n\n---\n\nThis guide explains how to install and configure all supported AI coding CLI tools\nto use **OmniRoute** as the unified backend, giving you centralized key management,\ncost tracking, model switching, and request logging across every tool.\n\n---\n\n## How It Works\n\n```\nClaude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot\n │\n ▼ (all point to OmniRoute)\n http://YOUR_SERVER:20128/v1\n │\n ▼ (OmniRoute routes to the right provider)\n Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...\n```\n\n**Benefits:**\n\n- One API key to manage all tools\n- Cost tracking across all CLIs in the dashboard\n- Model switching without reconfiguring every tool\n- Works locally and on remote servers (VPS)\n\n---\n\n## Supported Tools (Dashboard Source of Truth)\n\nThe dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`.\nCurrent list (v3.0.0-rc.16):\n\n| Tool | ID | Command | Setup Mode | Install Method |\n| ------------------ | ------------- | ---------- | ---------- | -------------- |\n| **Claude Code** | `claude` | `claude` | env | npm |\n| **OpenAI Codex** | `codex` | `codex` | custom | npm |\n| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI |\n| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI |\n| **Cursor** | `cursor` | app | guide | desktop app |\n| **Cline** | `cline` | `cline` | custom | npm |\n| **Kilo Code** | `kilo` | `kilocode` | custom | npm |\n| **Continue** | `continue` | extension | guide | VS Code |\n| **Antigravity** | `antigravity` | internal | mitm | OmniRoute |\n| **GitHub Copilot** | `copilot` | extension | custom | VS Code |\n| **OpenCode** | `opencode` | `opencode` | guide | npm |\n| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI |\n| **Qwen Code** | `qwen` | `qwen` | custom | npm |\n\n### CLI fingerprint sync (Agents + Settings)\n\n`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`.\nThis keeps provider IDs aligned with CLI cards and legacy IDs.\n\n| CLI ID | Fingerprint Provider ID |\n| ---------------------------------------------------------------------------------------------------- | ----------------------- |\n| `kilo` | `kilocode` |\n| `copilot` | `github` |\n| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID |\n\nLegacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`.\n\n---\n\n## Step 1 — Get an OmniRoute API Key\n\n1. Open the OmniRoute dashboard → **API Manager** (`/dashboard/api-manager`)\n2. Click **Create API Key**\n3. Give it a name (e.g. `cli-tools`) and select all permissions\n4. Copy the key — you'll need it for every CLI below\n\n> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`\n\n---\n\n## Step 2 — Install CLI Tools\n\nAll npm-based tools require Node.js 18+:\n\n```bash\n# Claude Code (Anthropic)\nnpm install -g @anthropic-ai/claude-code\n\n# OpenAI Codex\nnpm install -g @openai/codex\n\n# OpenCode\nnpm install -g opencode-ai\n\n# Cline\nnpm install -g cline\n\n# KiloCode\nnpm install -g kilocode\n\n# Kiro CLI (Amazon — requires curl + unzip)\napt-get install -y unzip # on Debian/Ubuntu\ncurl -fsSL https://cli.kiro.dev/install | bash\nexport PATH=\"$HOME/.local/bin:$PATH\" # add to ~/.bashrc\n```\n\n**Verify:**\n\n```bash\nclaude --version # 2.x.x\ncodex --version # 0.x.x\nopencode --version # x.x.x\ncline --version # 2.x.x\nkilocode --version # x.x.x (or: kilo --version)\nkiro-cli --version # 1.x.x\n```\n\n---\n\n## Step 3 — Set Global Environment Variables\n\nAdd to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`:\n\n```bash\n# OmniRoute Universal Endpoint\nexport OPENAI_BASE_URL=\"http://localhost:20128/v1\"\nexport OPENAI_API_KEY=\"sk-your-omniroute-key\"\nexport ANTHROPIC_BASE_URL=\"http://localhost:20128/v1\"\nexport ANTHROPIC_API_KEY=\"sk-your-omniroute-key\"\nexport GEMINI_BASE_URL=\"http://localhost:20128/v1\"\nexport GEMINI_API_KEY=\"sk-your-omniroute-key\"\n```\n\n> For a **remote server** replace `localhost:20128` with the server IP or domain,\n> e.g. `http://192.168.0.15:20128`.\n\n---\n\n## Step 4 — Configure Each Tool\n\n### Claude Code\n\n```bash\n# Via CLI:\nclaude config set --global api-base-url http://localhost:20128/v1\n\n# Or create ~/.claude/settings.json:\nmkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF\n{\n \"apiBaseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"sk-your-omniroute-key\"\n}\nEOF\n```\n\n**Test:** `claude \"say hello\"`\n\n---\n\n### OpenAI Codex\n\n```bash\nmkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF\nmodel: auto\napiKey: sk-your-omniroute-key\napiBaseUrl: http://localhost:20128/v1\nEOF\n```\n\n**Test:** `codex \"what is 2+2?\"`\n\n---\n\n### OpenCode\n\n```bash\nmkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF\n[provider.openai]\nbase_url = \"http://localhost:20128/v1\"\napi_key = \"sk-your-omniroute-key\"\nEOF\n```\n\n**Test:** `opencode`\n\n---\n\n### Cline (CLI or VS Code)\n\n**CLI mode:**\n\n```bash\nmkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF\n{\n \"apiProvider\": \"openai\",\n \"openAiBaseUrl\": \"http://localhost:20128/v1\",\n \"openAiApiKey\": \"sk-your-omniroute-key\"\n}\nEOF\n```\n\n**VS Code mode:**\nCline extension settings → API Provider: `OpenAI Compatible` → Base URL: `http://localhost:20128/v1`\n\nOr use the OmniRoute dashboard → **CLI Tools → Cline → Apply Config**.\n\n---\n\n### KiloCode (CLI or VS Code)\n\n**CLI mode:**\n\n```bash\nkilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key\n```\n\n**VS Code settings:**\n\n```json\n{\n \"kilo-code.openAiBaseUrl\": \"http://localhost:20128/v1\",\n \"kilo-code.apiKey\": \"sk-your-omniroute-key\"\n}\n```\n\nOr use the OmniRoute dashboard → **CLI Tools → KiloCode → Apply Config**.\n\n---\n\n### Continue (VS Code Extension)\n\nEdit `~/.continue/config.yaml`:\n\n```yaml\nmodels:\n - name: OmniRoute\n provider: openai\n model: auto\n apiBase: http://localhost:20128/v1\n apiKey: sk-your-omniroute-key\n default: true\n```\n\nRestart VS Code after editing.\n\n---\n\n### Kiro CLI (Amazon)\n\n```bash\n# Login to your AWS/Kiro account:\nkiro-cli login\n\n# The CLI uses its own auth — OmniRoute is not needed as backend for Kiro CLI itself.\n# Use kiro-cli alongside OmniRoute for other tools.\nkiro-cli status\n```\n\n---\n\n### Qwen Code (Alibaba)\n\nQwen Code supports OpenAI-compatible API endpoints via environment variables or `settings.json`.\n\n**Option 1: Environment variables (`~/.qwen/.env`)**\n\n```bash\nmkdir -p ~/.qwen && cat > ~/.qwen/.env << EOF\nOPENAI_API_KEY=\"sk-your-omniroute-key\"\nOPENAI_BASE_URL=\"http://localhost:20128/v1\"\nOPENAI_MODEL=\"auto\"\nEOF\n```\n\n**Option 2: `settings.json` with model providers**\n\n```json\n// ~/.qwen/settings.json\n{\n \"env\": {\n \"OPENAI_API_KEY\": \"sk-your-omniroute-key\",\n \"OPENAI_BASE_URL\": \"http://localhost:20128/v1\"\n },\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"omniroute-default\",\n \"name\": \"OmniRoute (Auto)\",\n \"envKey\": \"OPENAI_API_KEY\",\n \"baseUrl\": \"http://localhost:20128/v1\"\n }\n ]\n }\n}\n```\n\n**Option 3: Inline CLI flags**\n\n```bash\nOPENAI_BASE_URL=\"http://localhost:20128/v1\" \\\nOPENAI_API_KEY=\"sk-your-omniroute-key\" \\\nOPENAI_MODEL=\"auto\" \\\nqwen\n```\n\n> For a **remote server** replace `localhost:20128` with the server IP or domain.\n\n**Test:** `qwen \"say hello\"`\n\n### Cursor (Desktop App)\n\n> **Note:** Cursor routes requests through its cloud. For OmniRoute integration,\n> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL.\n\nVia GUI: **Settings → Models → OpenAI API Key**\n\n- Base URL: `https://your-domain.com/v1`\n- API Key: your OmniRoute key\n\n---\n\n## Dashboard Auto-Configuration\n\nThe OmniRoute dashboard automates configuration for most tools:\n\n1. Go to `http://localhost:20128/dashboard/cli-tools`\n2. Expand any tool card\n3. Select your API key from the dropdown\n4. Click **Apply Config** (if tool is detected as installed)\n5. Or copy the generated config snippet manually\n\n---\n\n## Built-in Agents: Droid & OpenClaw\n\n**Droid** and **OpenClaw** are AI agents built directly into OmniRoute — no installation needed.\nThey run as internal routes and use OmniRoute's model routing automatically.\n\n- Access: `http://localhost:20128/dashboard/agents`\n- Configure: same combos and providers as all other tools\n- No API key or CLI install required\n\n---\n\n## Available API Endpoints\n\n| Endpoint | Description | Use For |\n| -------------------------- | ----------------------------- | --------------------------- |\n| `/v1/chat/completions` | Standard chat (all providers) | All modern tools |\n| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows |\n| `/v1/completions` | Legacy text completions | Older tools using `prompt:` |\n| `/v1/embeddings` | Text embeddings | RAG, search |\n| `/v1/images/generations` | Image generation | GPT-Image, Flux, etc. |\n| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS |\n| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI |\n\n---\n\n## Feilsøking\n\n| Error | Cause | Fix |\n| ------------------------- | ----------------------- | ------------------------------------------ |\n| `Connection refused` | OmniRoute not running | `pm2 start omniroute` |\n| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` |\n| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` |\n| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` |\n| CLI shows \"not installed\" | Binary not in PATH | Check `which <command>` |\n| `kiro-cli: not found` | Not in PATH | `export PATH=\"$HOME/.local/bin:$PATH\"` |\n\n---\n\n## Quick Setup Script (One Command)\n\n```bash\n# Install all CLIs and configure for OmniRoute (replace with your key and server URL)\nOMNIROUTE_URL=\"http://localhost:20128/v1\"\nOMNIROUTE_KEY=\"sk-your-omniroute-key\"\n\nnpm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code\n\n# Kiro CLI\napt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash\n\n# Write configs\nmkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue\n\ncat > ~/.claude/settings.json <<< \"{\\\"apiBaseUrl\\\":\\\"$OMNIROUTE_URL\\\",\\\"apiKey\\\":\\\"$OMNIROUTE_KEY\\\"}\"\ncat > ~/.codex/config.yaml <<< \"model: auto\\napiKey: $OMNIROUTE_KEY\\napiBaseUrl: $OMNIROUTE_URL\"\ncat >> ~/.bashrc << EOF\nexport OPENAI_BASE_URL=\"$OMNIROUTE_URL\"\nexport OPENAI_API_KEY=\"$OMNIROUTE_KEY\"\nexport ANTHROPIC_BASE_URL=\"$OMNIROUTE_URL\"\nexport ANTHROPIC_API_KEY=\"$OMNIROUTE_KEY\"\nEOF\n\nsource ~/.bashrc\necho \"✅ All CLIs installed and configured for OmniRoute\"\n```\n"}, "8a1d9beb55fe825bd132c8696117046258869a79": {"t": 1785764410.947035, "n": 13216, "h": "2c6b46e0ca45ef6d", "c": "# CLI Tools Setup Guide — OmniRoute (Norsk)\n\n🌐 **Languages:** 🇺🇸 [English](../../../../docs/CLI-TOOLS.md) · 🇸🇦 [ar](../../ar/docs/CLI-TOOLS.md) · 🇧🇬 [bg](../../bg/docs/CLI-TOOLS.md) · 🇧🇩 [bn](../../bn/docs/CLI-TOOLS.md) · 🇨🇿 [cs](../../cs/docs/CLI-TOOLS.md) · 🇩🇰 [da](../../da/docs/CLI-TOOLS.md) · 🇩🇪 [de](../../de/docs/CLI-TOOLS.md) · 🇪🇸 [es](../../es/docs/CLI-TOOLS.md) · 🇮🇷 [fa](../../fa/docs/CLI-TOOLS.md) · 🇫🇮 [fi](../../fi/docs/CLI-TOOLS.md) · 🇫🇷 [fr](../../fr/docs/CLI-TOOLS.md) · 🇮🇳 [gu](../../gu/docs/CLI-TOOLS.md) · 🇮🇱 [he](../../he/docs/CLI-TOOLS.md) · 🇮🇳 [hi](../../hi/docs/CLI-TOOLS.md) · 🇭🇺 [hu](../../hu/docs/CLI-TOOLS.md) · 🇮🇩 [id](../../id/docs/CLI-TOOLS.md) · 🇮🇹 [it](../../it/docs/CLI-TOOLS.md) · 🇯🇵 [ja](../../ja/docs/CLI-TOOLS.md) · 🇰🇷 [ko](../../ko/docs/CLI-TOOLS.md) · 🇮🇳 [mr](../../mr/docs/CLI-TOOLS.md) · 🇲🇾 [ms](../../ms/docs/CLI-TOOLS.md) · 🇳🇱 [nl](../../nl/docs/CLI-TOOLS.md) · 🇳🇴 [no](../../no/docs/CLI-TOOLS.md) · 🇵🇭 [phi](../../phi/docs/CLI-TOOLS.md) · 🇵🇱 [pl](../../pl/docs/CLI-TOOLS.md) · 🇵🇹 [pt](../../pt/docs/CLI-TOOLS.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) · 🇷🇴 [ro](../../ro/docs/CLI-TOOLS.md) · 🇷🇺 [ru](../../ru/docs/CLI-TOOLS.md) · 🇸🇰 [sk](../../sk/docs/CLI-TOOLS.md) · 🇸🇪 [sv](../../sv/docs/CLI-TOOLS.md) · 🇰🇪 [sw](../../sw/docs/CLI-TOOLS.md) · 🇮🇳 [ta](../../ta/docs/CLI-TOOLS.md) · 🇮🇳 [te](../../te/docs/CLI-TOOLS.md) · 🇹🇭 [th](../../th/docs/CLI-TOOLS.md) · 🇹🇷 [tr](../../tr/docs/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) · 🇵🇰 [ur](../../ur/docs/CLI-TOOLS.md) · 🇻🇳 [vi](../../vi/docs/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/CLI-TOOLS.md)\n\n---\n\nThis guide explains how to install and configure all supported AI coding CLI tools\nto use **OmniRoute** as the unified backend, giving you centralized key management,\ncost tracking, model switching, and request logging across every tool.\n\n---\n\n## How It Works\n\n```\nClaude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot\n │\n ▼ (all point to OmniRoute)\n http://YOUR_SERVER:20128/v1\n │\n ▼ (OmniRoute routes to the right provider)\n Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...\n```\n\n**Benefits:**\n\n- One API key to manage all tools\n- Cost tracking across all CLIs in the dashboard\n- Model switching without reconfiguring every tool\n- Works locally and on remote servers (VPS)\n\n---\n\n## Supported Tools (Dashboard Source of Truth)\n\nThe dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`.\nCurrent list (v3.0.0-rc.16):\n\n| Tool | ID | Command | Setup Mode | Install Method |\n| ------------------ | ------------- | ---------- | ---------- | -------------- |\n| **Claude Code** | `claude` | `claude` | env | npm |\n| **OpenAI Codex** | `codex` | `codex` | custom | npm |\n| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI |\n| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI |\n| **Cursor** | `cursor` | app | guide | desktop app |\n| **Cline** | `cline` | `cline` | custom | npm |\n| **Kilo Code** | `kilo` | `kilocode` | custom | npm |\n| **Continue** | `continue` | extension | guide | VS Code |\n| **Antigravity** | `antigravity` | internal | mitm | OmniRoute |\n| **GitHub Copilot** | `copilot` | extension | custom | VS Code |\n| **OpenCode** | `opencode` | `opencode` | guide | npm |\n| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI |\n| **Qwen Code** | `qwen` | `qwen` | custom | npm |\n\n### CLI fingerprint sync (Agents + Settings)\n\n`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`.\nThis keeps provider IDs aligned with CLI cards and legacy IDs.\n\n| CLI ID | Fingerprint Provider ID |\n| ---------------------------------------------------------------------------------------------------- | ----------------------- |\n| `kilo` | `kilocode` |\n| `copilot` | `github` |\n| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID |\n\nLegacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`.\n\n---\n\n## Step 1 — Get an OmniRoute API Key\n\n1. Open the OmniRoute dashboard → **API Manager** (`/dashboard/api-manager`)\n2. Click **Create API Key**\n3. Give it a name (e.g. `cli-tools`) and select all permissions\n4. Copy the key — you'll need it for every CLI below\n\n> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`\n\n---\n\n## Step 2 — Install CLI Tools\n\nAll npm-based tools require Node.js 18+:\n\n```bash\n# Claude Code (Anthropic)\nnpm install -g @anthropic-ai/claude-code\n\n# OpenAI Codex\nnpm install -g @openai/codex\n\n# OpenCode\nnpm install -g opencode-ai\n\n# Cline\nnpm install -g cline\n\n# KiloCode\nnpm install -g kilocode\n\n# Kiro CLI (Amazon — requires curl + unzip)\napt-get install -y unzip # on Debian/Ubuntu\ncurl -fsSL https://cli.kiro.dev/install | bash\nexport PATH=\"$HOME/.local/bin:$PATH\" # add to ~/.bashrc\n```\n\n**Verify:**\n\n```bash\nclaude --version # 2.x.x\ncodex --version # 0.x.x\nopencode --version # x.x.x\ncline --version # 2.x.x\nkilocode --version # x.x.x (or: kilo --version)\nkiro-cli --version # 1.x.x\n```\n\n---\n\n## Step 3 — Set Global Environment Variables\n\nAdd to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`:\n\n```bash\n# OmniRoute Universal Endpoint\nexport OPENAI_BASE_URL=\"http://localhost:20128/v1\"\nexport OPENAI_API_KEY=\"sk-your-omniroute-key\"\nexport ANTHROPIC_BASE_URL=\"http://localhost:20128/v1\"\nexport ANTHROPIC_API_KEY=\"sk-your-omniroute-key\"\nexport GEMINI_BASE_URL=\"http://localhost:20128/v1\"\nexport GEMINI_API_KEY=\"sk-your-omniroute-key\"\n```\n\n> For a **remote server** replace `localhost:20128` with the server IP or domain,\n> e.g. `http://192.168.0.15:20128`.\n\n---\n\n## Step 4 — Configure Each Tool\n\n### Claude Code\n\n```bash\n# Via CLI:\nclaude config set --global api-base-url http://localhost:20128/v1\n\n# Or create ~/.claude/settings.json:\nmkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF\n{\n \"apiBaseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"sk-your-omniroute-key\"\n}\nEOF\n```\n\n**Test:** `claude \"say hello\"`\n\n---\n\n### OpenAI Codex\n\n```bash\nmkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF\nmodel: auto\napiKey: sk-your-omniroute-key\napiBaseUrl: http://localhost:20128/v1\nEOF\n```\n\n**Test:** `codex \"what is 2+2?\"`\n\n---\n\n### OpenCode\n\n```bash\nmkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF\n[provider.openai]\nbase_url = \"http://localhost:20128/v1\"\napi_key = \"sk-your-omniroute-key\"\nEOF\n```\n\n**Test:** `opencode`\n\n---\n\n### Cline (CLI or VS Code)\n\n**CLI mode:**\n\n```bash\nmkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF\n{\n \"apiProvider\": \"openai\",\n \"openAiBaseUrl\": \"http://localhost:20128/v1\",\n \"openAiApiKey\": \"sk-your-omniroute-key\"\n}\nEOF\n```\n\n**VS Code mode:**\nCline extension settings → API Provider: `OpenAI Compatible` → Base URL: `http://localhost:20128/v1`\n\nOr use the OmniRoute dashboard → **CLI Tools → Cline → Apply Config**.\n\n---\n\n### KiloCode (CLI or VS Code)\n\n**CLI mode:**\n\n```bash\nkilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key\n```\n\n**VS Code settings:**\n\n```json\n{\n \"kilo-code.openAiBaseUrl\": \"http://localhost:20128/v1\",\n \"kilo-code.apiKey\": \"sk-your-omniroute-key\"\n}\n```\n\nOr use the OmniRoute dashboard → **CLI Tools → KiloCode → Apply Config**.\n\n---\n\n### Continue (VS Code Extension)\n\nEdit `~/.continue/config.yaml`:\n\n```yaml\nmodels:\n - name: OmniRoute\n provider: openai\n model: auto\n apiBase: http://localhost:20128/v1\n apiKey: sk-your-omniroute-key\n default: true\n```\n\nRestart VS Code after editing.\n\n---\n\n### Kiro CLI (Amazon)\n\n```bash\n# Login to your AWS/Kiro account:\nkiro-cli login\n\n# The CLI uses its own auth — OmniRoute is not needed as backend for Kiro CLI itself.\n# Use kiro-cli alongside OmniRoute for other tools.\nkiro-cli status\n```\n\n---\n\n### Qwen Code (Alibaba)\n\nQwen Code supports OpenAI-compatible API endpoints via environment variables or `settings.json`.\n\n**Option 1: Environment variables (`~/.qwen/.env`)**\n\n```bash\nmkdir -p ~/.qwen && cat > ~/.qwen/.env << EOF\nOPENAI_API_KEY=\"sk-your-omniroute-key\"\nOPENAI_BASE_URL=\"http://localhost:20128/v1\"\nOPENAI_MODEL=\"auto\"\nEOF\n```\n\n**Option 2: `settings.json` with model providers**\n\n```json\n// ~/.qwen/settings.json\n{\n \"env\": {\n \"OPENAI_API_KEY\": \"sk-your-omniroute-key\",\n \"OPENAI_BASE_URL\": \"http://localhost:20128/v1\"\n },\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"omniroute-default\",\n \"name\": \"OmniRoute (Auto)\",\n \"envKey\": \"OPENAI_API_KEY\",\n \"baseUrl\": \"http://localhost:20128/v1\"\n }\n ]\n }\n}\n```\n\n**Option 3: Inline CLI flags**\n\n```bash\nOPENAI_BASE_URL=\"http://localhost:20128/v1\" \\\nOPENAI_API_KEY=\"sk-your-omniroute-key\" \\\nOPENAI_MODEL=\"auto\" \\\nqwen\n```\n\n> For a **remote server** replace `localhost:20128` with the server IP or domain.\n\n**Test:** `qwen \"say hello\"`\n\n### Cursor (Desktop App)\n\n> **Note:** Cursor routes requests through its cloud. For OmniRoute integration,\n> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL.\n\nVia GUI: **Settings → Models → OpenAI API Key**\n\n- Base URL: `https://your-domain.com/v1`\n- API Key: your OmniRoute key\n\n---\n\n## Dashboard Auto-Configuration\n\nThe OmniRoute dashboard automates configuration for most tools:\n\n1. Go to `http://localhost:20128/dashboard/cli-tools`\n2. Expand any tool card\n3. Select your API key from the dropdown\n4. Click **Apply Config** (if tool is detected as installed)\n5. Or copy the generated config snippet manually\n\n---\n\n## Built-in Agents: Droid & OpenClaw\n\n**Droid** and **OpenClaw** are AI agents built directly into OmniRoute — no installation needed.\nThey run as internal routes and use OmniRoute's model routing automatically.\n\n- Access: `http://localhost:20128/dashboard/agents`\n- Configure: same combos and providers as all other tools\n- No API key or CLI install required\n\n---\n\n## Available API Endpoints\n\n| Endpoint | Description | Use For |\n| -------------------------- | ----------------------------- | --------------------------- |\n| `/v1/chat/completions` | Standard chat (all providers) | All modern tools |\n| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows |\n| `/v1/completions` | Legacy text completions | Older tools using `prompt:` |\n| `/v1/embeddings` | Text embeddings | RAG, search |\n| `/v1/images/generations` | Image generation | GPT-Image, Flux, etc. |\n| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS |\n| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI |\n\n---\n\n## Feilsøking\n\n| Error | Cause | Fix |\n| ------------------------- | ----------------------- | ------------------------------------------ |\n| `Connection refused` | OmniRoute not running | `pm2 start omniroute` |\n| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` |\n| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` |\n| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` |\n| CLI shows \"not installed\" | Binary not in PATH | Check `which <command>` |\n| `kiro-cli: not found` | Not in PATH | `export PATH=\"$HOME/.local/bin:$PATH\"` |\n\n---\n\n## Quick Setup Script (One Command)\n\n```bash\n# Install all CLIs and configure for OmniRoute (replace with your key and server URL)\nOMNIROUTE_URL=\"http://localhost:20128/v1\"\nOMNIROUTE_KEY=\"sk-your-omniroute-key\"\n\nnpm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code\n\n# Kiro CLI\napt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash\n\n# Write configs\nmkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue\n\ncat > ~/.claude/settings.json <<< \"{\\\"apiBaseUrl\\\":\\\"$OMNIROUTE_URL\\\",\\\"apiKey\\\":\\\"$OMNIROUTE_KEY\\\"}\"\ncat > ~/.codex/config.yaml <<< \"model: auto\\napiKey: $OMNIROUTE_KEY\\napiBaseUrl: $OMNIROUTE_URL\"\ncat >> ~/.bashrc << EOF\nexport OPENAI_BASE_URL=\"$OMNIROUTE_URL\"\nexport OPENAI_API_KEY=\"$OMNIROUTE_KEY\"\nexport ANTHROPIC_BASE_URL=\"$OMNIROUTE_URL\"\nexport ANTHROPIC_API_KEY=\"$OMNIROUTE_KEY\"\nEOF\n\nsource ~/.bashrc\necho \"✅ All CLIs installed and configured for OmniRoute\"\n```\n"}}, "docs/i18n/it/README.md": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1786067772.9702148, "n": 112458, "h": "c22821f94ef82c97", "c": "# 🚀 OmniRoute — The Free AI Gateway (Italiano)\n\n🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 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)\n\n</div>\n\n🌐 **Available in:** 🇺🇸 [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)\n\n---\n\n## 🖼️ Main Dashboard\n\n<div align=\"center\">\n <img src=\"./docs/screenshots/MainOmniRoute.png\" alt=\"OmniRoute Dashboard\" width=\"800\"/>\n</div>\n\n---\n\n## 📸 Dashboard Preview\n\n<details>\n<summary><b>Click to see dashboard screenshots</b></summary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n</details>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n <table>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openclaw/openclaw\">\n <img src=\"./public/providers/openclaw.png\" alt=\"OpenClaw\" width=\"48\"/><br/>\n <b>OpenClaw</b>\n </a><br/>\n <sub>⭐ 205K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/HKUDS/nanobot\">\n <img src=\"./public/providers/nanobot.png\" alt=\"NanoBot\" width=\"48\"/><br/>\n <b>NanoBot</b>\n </a><br/>\n <sub>⭐ 20.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/sipeed/picoclaw\">\n <img src=\"./public/providers/picoclaw.jpg\" alt=\"PicoClaw\" width=\"48\"/><br/>\n <b>PicoClaw</b>\n </a><br/>\n <sub>⭐ 14.6K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/zeroclaw-labs/zeroclaw\">\n <img src=\"./public/providers/zeroclaw.png\" alt=\"ZeroClaw\" width=\"48\"/><br/>\n <b>ZeroClaw</b>\n </a><br/>\n <sub>⭐ 9.9K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/nearai/ironclaw\">\n <img src=\"./public/providers/ironclaw.png\" alt=\"IronClaw\" width=\"48\"/><br/>\n <b>IronClaw</b>\n </a><br/>\n <sub>⭐ 2.1K</sub>\n </td>\n </tr>\n <tr>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anomalyco/opencode\">\n <img src=\"./public/providers/opencode.svg\" alt=\"OpenCode\" width=\"48\"/><br/>\n <b>OpenCode</b>\n </a><br/>\n <sub>⭐ 106K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/openai/codex\">\n <img src=\"./public/providers/codex.svg\" alt=\"Codex CLI\" width=\"48\"/><br/>\n <b>Codex CLI</b>\n </a><br/>\n <sub>⭐ 60.8K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/anthropics/claude-code\">\n <img src=\"./public/providers/claude.svg\" alt=\"Claude Code\" width=\"48\"/><br/>\n <b>Claude Code</b>\n </a><br/>\n <sub>⭐ 67.3K</sub>\n </td>\n <td align=\"center\" width=\"110\">\n <a href=\"https://github.com/Kilo-Org/kilocode\">\n <img src=\"./public/providers/kilocode.svg\" alt=\"Kilo Code\" width=\"48\"/><br/>\n <b>Kilo Code</b>\n </a><br/>\n <sub>⭐ 15.5K</sub>\n </td>\n </tr>\n </table>\n\n<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Subscription quota expires unused every month\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Rate limits stop you mid-coding\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Expensive APIs ($20-50/month per provider)\n- <img src=\"https://img.shields.io/badge/✗-e74c3c?style=flat-square\" height=\"16\"/> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http://localhost:20128/v1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n<details>\n<summary><b>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"</b></summary>\n\nDevelopers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard\n\n</details>\n\n<details>\n<summary><b>🔌 2. \"I need to use multiple providers but each has a different API\"</b></summary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE\n- **Think Tag Extraction** — Extracts `<think>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n</details>\n\n<details>\n<summary><b>🌐 3. \"My AI provider blocks my region/country\"</b></summary>\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n</details>\n\n<details>\n<summary><b>🆓 4. \"I want to use AI for coding but I have no money\"</b></summary>\n\nNot everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/<model>` prefix\n- **Free-Only Combos** — Chain `if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n</details>\n\n<details>\n<summary><b>🔒 5. \"I need to protect my AI gateway from unauthorized access\"</b></summary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist/blocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n</details>\n\n<details>\n<summary><b>🛑 6. \"My provider went down and I lost my coding flow\"</b></summary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n</details>\n\n<details>\n<summary><b>🔧 7. \"Configuring each AI tool is tedious and repetitive\"</b></summary>\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers\n\n</details>\n\n<details>\n<summary><b>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"</b></summary>\n\nClaude Code, Codex, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n</details>\n\n<details>\n<summary><b>📊 9. \"I don't know how much I'm spending or where\"</b></summary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n</details>\n\n<details>\n<summary><b>🐛 10. \"I can't diagnose errors and problems in AI calls\"</b></summary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n</details>\n\n<details>\n<summary><b>🏗️ 11. \"Deploying and maintaining the gateway is complex\"</b></summary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n</details>\n\n<details>\n<summary><b>🌍 12. \"The interface is English-only and my team doesn't speak English\"</b></summary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n</details>\n\n<details>\n<summary><b>🔄 13. \"I need more than chat — I need embeddings, images, audio\"</b></summary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `/v1/moderations` — Content safety checks\n- **Reranking** — `/v1/rerank` — Document relevance reranking\n- **Responses API** — Full `/v1/responses` support for Codex\n\n</details>\n\n<details>\n<summary><b>🧪 14. \"I have no way to test and compare quality across models\"</b></summary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n</details>\n\n<details>\n<summary><b>📈 15. \"I need to scale without losing performance\"</b></summary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime\n\n</details>\n\n<details>\n<summary><b>🤖 16. \"I want to control model behavior globally\"</b></summary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable/disable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `/v1/models` listing\n\n</details>\n\n<details>\n<summary><b>🧰 17. \"I need MCP tools as first-class product capabilities\"</b></summary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n</details>\n\n<details>\n<summary><b>🧠 18. \"I need A2A orchestration with sync + stream task paths\"</b></summary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n</details>\n\n<details>\n<summary><b>🛰️ 19. \"I need real MCP process health, not guessed status\"</b></summary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n</details>\n\n<details>\n<summary><b>📋 20. \"I need auditable MCP tool execution\"</b></summary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n</details>\n\n<details>\n<summary><b>🔐 21. \"I need scoped MCP permissions per integration\"</b></summary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n</details>\n\n<details>\n<summary><b>⚙️ 22. \"I need operational controls without redeploying\"</b></summary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n</details>\n\n<details>\n<summary><b>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"</b></summary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n</details>\n\n<details>\n<summary><b>🌊 24. \"I need active stream metrics for A2A load\"</b></summary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n</details>\n\n<details>\n<summary><b>🪪 25. \"I need standard agent discovery for clients\"</b></summary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n</details>\n\n<details>\n<summary><b>🧭 26. \"I need protocol discoverability in the product UX\"</b></summary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n</details>\n\n<details>\n<summary><b>🧪 27. \"I need end-to-end protocol validation with real clients\"</b></summary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n</details>\n\n<details>\n<summary><b>📡 28. \"I need unified observability across all interfaces\"</b></summary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n</details>\n\n<details>\n<summary><b>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"</b></summary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n</details>\n\n<details>\n<summary><b>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"</b></summary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n</details>\n\n<details>\n<summary><b>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"</b></summary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n</details>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Avvio Rapido\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Pass `--allow-build` at install time to enable native build scripts required by `better-sqlite3` and `@swc/core` (the `approve-builds -g` command is not supported for global installs on pnpm v11):\n>\n> ```bash\n> pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n<details>\n<summary><b>Void Linux (`xbps-src` template)</b></summary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit <zenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n</details>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Avvio Rapido\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr/) → Claude Sonnet/Haiku UNLIMITED\nQoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\nPollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key\nCloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day\nScaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day\nNVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\nCerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `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`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥\n> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw/) → qwen3-coder models UNLIMITED\n> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free\n> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day\n> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 → uses $200 free first\n [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **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 |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider/*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `/v1/moderations` safety checks |\n| 🔀 **Reranking** | `/v1/rerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection |\n| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |\n| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup/Restore** | Export/import and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n<details>\n<summary><b>🧩 MCP Setup (Model Context Protocol)</b></summary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n</details>\n\n<details>\n<summary><b>🤝 A2A Setup (Agent2Agent)</b></summary>\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n</details>\n\n<details>\n<summary><b>🧪 End-to-end protocol validation</b></summary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n</details>\n\n<details>\n<summary><b>💳 Subscription Providers</b></summary>\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n</details>\n\n<details>\n<summary><b>🔑 API Key Providers</b></summary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n</details>\n\n<details>\n<summary><b>💰 Cheap Providers (Backup)</b></summary>\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n</details>\n\n<details>\n<summary><b>🆓 FREE Providers (Emergency Backup)</b></summary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google/GitHub\n→ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n</details>\n\n<details>\n<summary><b>🎨 Create Combos</b></summary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n</details>\n\n<details>\n<summary><b>🔧 CLI Integration</b></summary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n</details>\n\n---\n\n## Risoluzione dei Problemi\n\n<details>\n<summary><b>Click to expand troubleshooting guide</b></summary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM/MiniMax\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n<a name=\"oauth-on-a-remote-server\"></a>\n<a name=\"oauth-em-servidor-remoto\"></a>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n## 🛠️ Tech Stack\n\n<details>\n<summary><b>Click to expand tech stack details</b></summary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n</details>\n\n---\n\n## Documentazione\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n<a href=\"https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left\" />\n </picture>\n</a>\n\n## 🌍 StarMapper\n\n<a href=\"https://starmapper.bruniaux.com/diegosouzapw/omniroute\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light\" />\n <img alt=\"StarMapper\" src=\"https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute\" />\n </picture>\n</a>\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licenza\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers who code 24/7</sub>\n <br/>\n <sub><a href=\"https://omniroute.online\">omniroute.online</a></sub>\n</div>\n<!-- GitHub Discussions enabled for community Q&A -->\n"}}, "src/lib/playground/types.ts": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1786068458.1939538, "n": 2976, "h": "a387f5d1662cb59d", "c": "// src/lib/playground/types.ts\n// Re-exports from codeExport + standalone pricing table\n\nexport type {\n PlaygroundEndpoint,\n ExportLanguage,\n ChatMessage,\n ToolDefinition,\n PlaygroundState,\n} from \"./codeExport\";\n\nexport { PlaygroundStateSchema, API_KEY_PLACEHOLDER, exportCode, exportAllLanguages, endpointToPath } from \"./codeExport\";\n\nexport type { ImprovePromptRequest, ImprovePromptResult } from \"./promptImprover\";\n\nexport {\n ImprovePromptRequestSchema,\n META_SYSTEM_PROMPT,\n buildImproveChatBody,\n parseImprovedContent,\n} from \"./promptImprover\";\n\n/**\n * Pricing entry for a model.\n * Label \"(estimated)\" indicates these are approximate values for UI display (D13).\n */\nexport interface ProviderPricing {\n /** Cost per 1k input tokens in USD. */\n inUsdPer1k: number;\n /** Cost per 1k output tokens in USD. */\n outUsdPer1k: number;\n /** Display label — always includes \"(estimated)\". */\n label: string;\n}\n\n/**\n * Static inline pricing table for popular models.\n * Used in client-side cost estimation (D13).\n * DO NOT use for billing — always labeled \"(estimated)\".\n *\n * Prices are approximate as of 2025. For real billing see /api/usage.\n */\nexport const MODEL_PRICING_TABLE: Record<string, ProviderPricing> = {\n \"gpt-4o\": {\n inUsdPer1k: 0.0025,\n outUsdPer1k: 0.01,\n label: \"(estimated)\",\n },\n \"gpt-4o-mini\": {\n inUsdPer1k: 0.00015,\n outUsdPer1k: 0.0006,\n label: \"(estimated)\",\n },\n \"claude-sonnet-4-6\": {\n inUsdPer1k: 0.003,\n outUsdPer1k: 0.015,\n label: \"(estimated)\",\n },\n \"claude-opus-4-7\": {\n inUsdPer1k: 0.015,\n outUsdPer1k: 0.075,\n label: \"(estimated)\",\n },\n \"claude-haiku-4-5\": {\n inUsdPer1k: 0.0008,\n outUsdPer1k: 0.004,\n label: \"(estimated)\",\n },\n \"gemini-2.5-pro\": {\n inUsdPer1k: 0.00125,\n outUsdPer1k: 0.01,\n label: \"(estimated)\",\n },\n \"gemini-2.0-flash\": {\n inUsdPer1k: 0.0001,\n outUsdPer1k: 0.0004,\n label: \"(estimated)\",\n },\n \"deepseek-chat\": {\n inUsdPer1k: 0.00014,\n outUsdPer1k: 0.00028,\n label: \"(estimated)\",\n },\n \"llama-3.3-70b\": {\n inUsdPer1k: 0.00059,\n outUsdPer1k: 0.00079,\n label: \"(estimated)\",\n },\n \"mistral-large\": {\n inUsdPer1k: 0.002,\n outUsdPer1k: 0.006,\n label: \"(estimated)\",\n },\n};\n\n/**\n * Look up pricing for a model by name.\n * Returns null if not found (use upstream usage data instead).\n */\nexport function getModelPricing(model: string): ProviderPricing | null {\n return MODEL_PRICING_TABLE[model] ?? null;\n}\n\n/**\n * Look up pricing for a model — alias with explicit `estimated: true` in return type.\n * Required by §3 contract: `getProviderPricing(model): { inUsdPer1k, outUsdPer1k, estimated: true } | null`.\n */\nexport function getProviderPricing(\n model: string,\n): { inUsdPer1k: number; outUsdPer1k: number; estimated: true } | null {\n const entry = MODEL_PRICING_TABLE[model];\n if (!entry) return null;\n return { inUsdPer1k: entry.inUsdPer1k, outUsdPer1k: entry.outUsdPer1k, estimated: true };\n}\n"}}}}
Reference in new issue View Git Blame Copy Permalink