🤖 feat: add OpenRouter provider support

Add official OpenRouter provider integration for access to 300+ models
through a single API. Fixes errors that occurred when using baseURL
override approach.

Changes:
- Install @openrouter/ai-sdk-provider package
- Add OpenRouter to aiService.ts createModel method
- Add OpenRouterProviderOptions to provider types
- Add OPENROUTER_API_KEY environment variable support
- Update docs/models.md with OpenRouter setup guide

OpenRouter provides:
- Universal model access (Anthropic, OpenAI, Google, Cerebras, etc.)
- Pay-as-you-go pricing with transparent per-token costs
- High availability with automatic failover
- Immediate access to new models

Usage:
  openrouter:anthropic/claude-3.5-sonnet
  openrouter:google/gemini-2.0-flash-thinking-exp
  openrouter:cerebras/glm-4.6
  openrouter:deepseek/deepseek-chat

_Generated with `cmux`_

Author: ammar-agent

.env.example

@@ -4,6 +4,7 @@
 # Required for integration tests when TEST_INTEGRATION=1
 ANTHROPIC_API_KEY=sk-ant-...
 OPENAI_API_KEY=sk-proj-...
+OPENROUTER_API_KEY=sk-or-v1-...
 
 # Optional: Set to 1 to run integration tests
 # Integration tests require API keys to be set

bun.lock

@@ -6,6 +6,7 @@
       "dependencies": {
         "@ai-sdk/anthropic": "^2.0.29",
         "@ai-sdk/openai": "^2.0.52",
+        "@openrouter/ai-sdk-provider": "^1.2.1",
         "@radix-ui/react-dialog": "^1.1.15",
         "@radix-ui/react-dropdown-menu": "^2.1.16",
         "@radix-ui/react-scroll-area": "^1.2.10",
@@ -405,6 +406,8 @@
 
     "@nodelib/fs.walk": ["@nodelib/fs.walk@1.2.8", "", { "dependencies": { "@nodelib/fs.scandir": "2.1.5", "fastq": "^1.6.0" } }, "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg=="],
 
+    "@openrouter/ai-sdk-provider": ["@openrouter/ai-sdk-provider@1.2.1", "", { "peerDependencies": { "ai": "^5.0.0", "zod": "^3.24.1 || ^v4" } }, "sha512-sDc+/tlEM9VTsYlZ3YMwD9AHinSNusdLFGQhtb50eo5r68U/yBixEHRsKEevqSspiX3V6J06hU7C25t4KE9iag=="],
+
     "@opentelemetry/api": ["@opentelemetry/api@1.9.0", "", {}, "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg=="],
 
     "@pkgjs/parseargs": ["@pkgjs/parseargs@0.11.0", "", {}, "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg=="],

docs/models.md

@@ -27,6 +27,36 @@ GPT-5 family of models:
 
 TODO: add issue link here.
 
+#### OpenRouter (Cloud)
+
+Access 300+ models from multiple providers through a single API:
+
+- `openrouter:anthropic/claude-3.5-sonnet`
+- `openrouter:google/gemini-2.0-flash-thinking-exp`
+- `openrouter:deepseek/deepseek-chat`
+- `openrouter:openai/gpt-4o`
+- Any model from [OpenRouter Models](https://openrouter.ai/models)
+
+**Setup:**
+
+1. Get your API key from [openrouter.ai](https://openrouter.ai/)
+2. Add to `~/.cmux/providers.jsonc`:
+
+```jsonc
+{
+  "openrouter": {
+    "apiKey": "sk-or-v1-...",
+  },
+}
+```
+
+**Benefits:**
+
+- Single API key for hundreds of models
+- Pay-as-you-go pricing with no monthly fees
+- Transparent per-token costs
+- Automatic failover for high availability
+
 #### Ollama (Local)
 
 Run models locally with Ollama. No API key required:
@@ -68,6 +98,10 @@ All providers are configured in `~/.cmux/providers.jsonc`. Example configuration
   "openai": {
     "apiKey": "sk-...",
   },
+  // Required for OpenRouter models
+  "openrouter": {
+    "apiKey": "sk-or-v1-...",
+  },
   // Optional for Ollama (only needed for custom URL)
   "ollama": {
     "baseUrl": "http://your-server:11434/api",

package.json

@@ -47,6 +47,7 @@
   "dependencies": {
     "@ai-sdk/anthropic": "^2.0.29",
     "@ai-sdk/openai": "^2.0.52",
+    "@openrouter/ai-sdk-provider": "^1.2.1",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-scroll-area": "^1.2.10",

src/services/aiService.ts

@@ -105,6 +105,7 @@ export async function preloadAISDKProviders(): Promise<void> {
     import("@ai-sdk/anthropic"),
     import("@ai-sdk/openai"),
     import("ollama-ai-provider-v2"),
+    import("@openrouter/ai-sdk-provider"),
   ]);
 }
 
@@ -416,6 +417,30 @@ export class AIService extends EventEmitter {
         return Ok(provider(modelId));
       }
 
+      // Handle OpenRouter provider
+      if (providerName === "openrouter") {
+        if (!providerConfig.apiKey) {
+          return Err({
+            type: "api_key_not_found",
+            provider: providerName,
+          });
+        }
+        // Use custom fetch if provided, otherwise default with unlimited timeout
+        const baseFetch =
+          typeof providerConfig.fetch === "function"
+            ? (providerConfig.fetch as typeof fetch)
+            : defaultFetchWithUnlimitedTimeout;
+
+        // Lazy-load OpenRouter provider to reduce startup time
+        const { createOpenRouter } = await import("@openrouter/ai-sdk-provider");
+        const provider = createOpenRouter({
+          ...providerConfig,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+          fetch: baseFetch as any,
+        });
+        return Ok(provider(modelId));
+      }
+
       return Err({
         type: "provider_not_supported",
         provider: providerName,

src/types/providerOptions.ts

@@ -37,6 +37,14 @@ export interface OpenAIProviderOptions {
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface OllamaProviderOptions {}
 
+/**
+ * OpenRouter-specific options
+ * Currently empty - OpenRouter handles provider-specific options via extraBody.
+ * This interface is provided for future extensibility.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface OpenRouterProviderOptions {}
+
 /**
  * Cmux provider options - used by both frontend and backend
  */
@@ -45,4 +53,5 @@ export interface CmuxProviderOptions {
   anthropic?: AnthropicProviderOptions;
   openai?: OpenAIProviderOptions;
   ollama?: OllamaProviderOptions;
+  openrouter?: OpenRouterProviderOptions;
 }

src/utils/providers/ensureProvidersConfig.ts

@@ -49,6 +49,11 @@ const buildProvidersFromEnv = (env: NodeJS.ProcessEnv): ProvidersConfig => {
     providers.openai = entry;
   }
 
+  const openRouterKey = trim(env.OPENROUTER_API_KEY);
+  if (openRouterKey.length > 0) {
+    providers.openrouter = { apiKey: openRouterKey };
+  }
+
   if (!providers.openai) {
     const azureKey = trim(env.AZURE_OPENAI_API_KEY);
     const azureEndpoint = trim(env.AZURE_OPENAI_ENDPOINT);
@@ -97,7 +102,7 @@ export const ensureProvidersConfig = (
   const providersFromEnv = buildProvidersFromEnv(env);
   if (!hasAnyConfiguredProvider(providersFromEnv)) {
     throw new Error(
-      "No provider credentials found. Configure providers.jsonc or set ANTHROPIC_API_KEY / OPENAI_API_KEY."
+      "No provider credentials found. Configure providers.jsonc or set ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY."
     );
   }