openclaw-freerouter 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 1.3.0 (2026-02-14)
+
+Initial release as OpenClaw plugin.
+
+### Features
+- 14-dimension weighted classifier for smart model routing
+- Auto-classify requests → route to cheapest capable model
+- Tier system: SIMPLE → MEDIUM → COMPLEX → REASONING
+- Agentic task detection with separate tier configs
+- Mode overrides (`/max`, `[simple]`, `reasoning mode:`)
+- Adaptive thinking for Opus 4.6+
+- Configurable providers, tiers, and boundaries via plugin config
+- Fallback chains per tier
+- Timeout + stall detection per tier
+- OpenAI-compatible API (Anthropic Messages ↔ OpenAI translation)
+- Tool call support (OpenAI ↔ Anthropic conversion)
+- Streaming with SSE format translation
+- Zero external dependencies
+
+### Plugin Integration
+- Starts/stops with OpenClaw gateway lifecycle
+- Config via `plugins.entries.freerouter.config` in openclaw.json
+- Auto-registers as `freerouter` provider
+- Reads auth from OpenClaw's auth-profiles.json

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenFreeRouter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @openfreerouter/openclaw-freerouter
+
+**FreeRouter** — Smart model router for OpenClaw. Auto-classifies requests using a 14-dimension weighted scorer and routes to the cheapest capable model using your own API keys.
+
+## Install
+
+```bash
+openclaw plugins install @openfreerouter/openclaw-freerouter
+```
+
+Or install from local path:
+
+```bash
+openclaw plugins install ./openclaw-freerouter
+```
+
+## Configuration
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "freerouter": {
+        "config": {
+          "port": 18800,
+          "host": "127.0.0.1",
+          "providers": {
+            "anthropic": {
+              "baseUrl": "https://api.anthropic.com",
+              "api": "anthropic"
+            },
+            "kimi-coding": {
+              "baseUrl": "https://api.kimi.com/coding/v1",
+              "api": "openai",
+              "headers": { "User-Agent": "KimiCLI/0.77" }
+            }
+          },
+          "tiers": {
+            "SIMPLE":    { "primary": "kimi-coding/kimi-for-coding", "fallback": ["anthropic/claude-haiku-4-5"] },
+            "MEDIUM":    { "primary": "anthropic/claude-sonnet-4-5", "fallback": ["anthropic/claude-opus-4-6"] },
+            "COMPLEX":   { "primary": "anthropic/claude-opus-4-6", "fallback": ["anthropic/claude-haiku-4-5"] },
+            "REASONING": { "primary": "anthropic/claude-opus-4-6", "fallback": ["anthropic/claude-haiku-4-5"] }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+All config fields are optional — sensible defaults are built in.
+
+## How It Works
+
+1. **Classify**: Each request is scored across 14 dimensions (code presence, reasoning markers, technical terms, creativity, etc.)
+2. **Route**: Score maps to a tier (SIMPLE → MEDIUM → COMPLEX → REASONING)
+3. **Forward**: Request is forwarded to the tier's primary model, with automatic fallback
+4. **Translate**: Anthropic Messages API ↔ OpenAI format translation happens transparently
+
+## Tiers
+
+| Tier | Default Model | Use Case |
+|------|--------------|----------|
+| SIMPLE | Kimi K2.5 | Greetings, facts, translations |
+| MEDIUM | Claude Sonnet 4.5 | Code, conversation, tool use |
+| COMPLEX | Claude Opus 4.6 | Architecture, debugging, analysis |
+| REASONING | Claude Opus 4.6 | Proofs, formal reasoning, deep analysis |
+
+## Mode Overrides
+
+Force a specific tier in your prompt:
+
+- `/max prove that P ≠ NP` → REASONING
+- `simple mode: what's 2+2` → SIMPLE
+- `[complex] review this architecture` → COMPLEX
+
+## Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/chat/completions` | POST | OpenAI-compatible chat |
+| `/v1/models` | GET | List available models |
+| `/health` | GET | Health check |
+| `/stats` | GET | Request statistics |
+| `/config` | GET | Show sanitized config |
+| `/reload` | POST | Reload auth keys |
+| `/reload-config` | POST | Reload config + auth |
+
+## Use as Default Model
+
+Set your default model to `freerouter/auto` in openclaw.json:
+
+```json
+{
+  "model": "freerouter/auto"
+}
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,63 @@
+/**
+ * FreeRouter — OpenClaw Plugin Entry Point
+ *
+ * Starts the FreeRouter proxy server as a background service
+ * and registers it as a model provider.
+ */
+
+import { startServer, stopServer } from "./src/server.js";
+
+export default {
+  id: "freerouter",
+  name: "FreeRouter",
+
+  async register(api: any) {
+    // Read plugin config
+    const pluginConfig = api.config?.plugins?.entries?.freerouter?.config ?? {};
+    const port = pluginConfig.port ?? 18800;
+    const host = pluginConfig.host ?? "127.0.0.1";
+
+    api.log?.info?.(`[FreeRouter] Starting proxy on ${host}:${port}...`);
+
+    try {
+      // Start the proxy server
+      await startServer({
+        port,
+        host,
+        pluginConfig,
+      });
+
+      api.log?.info?.(`[FreeRouter] Proxy running on http://${host}:${port}`);
+
+      // Register as a provider if the API supports it
+      if (api.registerProvider) {
+        api.registerProvider({
+          id: "freerouter",
+          name: "FreeRouter",
+          baseUrl: `http://${host}:${port}/v1`,
+          api: "openai",
+          models: [
+            { id: "freerouter/auto", name: "FreeRouter Auto", description: "Auto-routes to best model" },
+          ],
+        });
+        api.log?.info?.("[FreeRouter] Registered as provider 'freerouter'");
+      }
+
+      // Register shutdown handler
+      if (api.onShutdown) {
+        api.onShutdown(async () => {
+          api.log?.info?.("[FreeRouter] Shutting down proxy...");
+          await stopServer();
+        });
+      }
+    } catch (err: any) {
+      api.log?.error?.(`[FreeRouter] Failed to start: ${err.message}`);
+      throw err;
+    }
+  },
+};
+
+// Re-export router for programmatic use
+export { route, DEFAULT_ROUTING_CONFIG } from "./src/router/index.js";
+export { startServer, stopServer } from "./src/server.js";
+export type { RoutingDecision, Tier, RoutingConfig } from "./src/router/types.js";

package/openclaw.plugin.json

@@ -0,0 +1,25 @@
+{
+  "id": "freerouter",
+  "name": "FreeRouter",
+  "description": "Smart model router — auto-classify requests and route to the cheapest capable model using your own API keys",
+  "version": "1.3.0",
+  "providers": ["freerouter"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "port": { "type": "number", "default": 18800 },
+      "host": { "type": "string", "default": "127.0.0.1" },
+      "providers": { "type": "object" },
+      "tiers": { "type": "object" },
+      "agenticTiers": { "type": "object" },
+      "tierBoundaries": { "type": "object" },
+      "thinking": { "type": "object" },
+      "auth": { "type": "object" }
+    }
+  },
+  "uiHints": {
+    "port": { "label": "Proxy Port", "placeholder": "18800" },
+    "host": { "label": "Bind Address", "placeholder": "127.0.0.1" }
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "openclaw-freerouter",
+  "version": "1.3.0",
+  "description": "FreeRouter plugin for OpenClaw — smart model routing with your own API keys",
+  "type": "module",
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "ai-router",
+    "model-router",
+    "freerouter",
+    "llm",
+    "proxy"
+  ],
+  "author": "OpenFreeRouter",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openfreerouter/openclaw-freerouter"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "typescript": "^5.9.3"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,128 @@
+/**
+ * ClawRouter Auth — loads API keys from OpenClaw auth-profiles.json
+ * Zero-dep, reads from ~/.openclaw/agents/main/agent/auth-profiles.json
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { getConfig } from "./config.js";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { logger } from "./logger.js";
+
+export type ProviderAuth = {
+  provider: string;
+  profileName: string;
+  token?: string;   // Anthropic OAuth token
+  apiKey?: string;   // API key (Kimi, OpenAI)
+};
+
+type AuthProfilesFile = {
+  version: number;
+  profiles: Record<string, {
+    type: "token" | "api_key";
+    provider: string;
+    token?: string;
+    key?: string;
+  }>;
+  lastGood?: Record<string, string>;
+};
+
+let authCache: Map<string, ProviderAuth> | null = null;
+
+function loadAuthProfiles(): Map<string, ProviderAuth> {
+  // Get path from config, fall back to default
+  const cfg = getConfig();
+  const authCfg = cfg.auth;
+  const defaultAuth = authCfg[authCfg.default] as { type?: string; profilesPath?: string } | undefined;
+  let filePath: string;
+  if (defaultAuth?.profilesPath) {
+    const p = defaultAuth.profilesPath;
+    filePath = p.startsWith("~/") ? join(homedir(), p.slice(2)) : p;
+  } else {
+    filePath = join(homedir(), ".openclaw", "agents", "main", "agent", "auth-profiles.json");
+  }
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const data: AuthProfilesFile = JSON.parse(raw);
+    const map = new Map<string, ProviderAuth>();
+
+    // Build a map of provider → best profile (prefer lastGood)
+    const lastGood = data.lastGood ?? {};
+
+    for (const [name, profile] of Object.entries(data.profiles)) {
+      const provider = profile.provider;
+      const existing = map.get(provider);
+
+      // Prefer lastGood profile
+      const isLastGood = lastGood[provider] === name;
+      if (existing && !isLastGood) continue;
+
+      map.set(provider, {
+        provider,
+        profileName: name,
+        token: profile.type === "token" ? profile.token : undefined,
+        apiKey: profile.type === "api_key" ? profile.key : undefined,
+      });
+    }
+
+    logger.info(`Loaded auth for providers: ${[...map.keys()].join(", ")}`);
+    return map;
+  } catch (err) {
+    logger.error("Failed to load auth-profiles.json:", err);
+    return new Map();
+  }
+}
+
+export function getAuth(provider: string): ProviderAuth | undefined {
+  // Check env var auth first (per-provider config override)
+  const envAuth = getEnvAuth(provider);
+  if (envAuth) return envAuth;
+
+  // Fall back to auth-profiles.json
+  if (!authCache) {
+    authCache = loadAuthProfiles();
+  }
+  return authCache.get(provider);
+}
+
+
+
+/**
+ * Get auth from environment variable (for providers with auth.type=env in config).
+ */
+function getEnvAuth(provider: string): ProviderAuth | undefined {
+  const cfg = getConfig();
+  const providerCfg = cfg.providers[provider];
+  if (!providerCfg?.auth || providerCfg.auth.type !== "env") return undefined;
+  const envKey = providerCfg.auth.key;
+  if (!envKey) return undefined;
+  const value = process.env[envKey];
+  if (!value) return undefined;
+  return {
+    provider,
+    profileName: envKey,
+    apiKey: value,
+  };
+}
+
+export function reloadAuth(): void {
+  authCache = null;
+  logger.info("Auth cache cleared, will reload on next access");
+}
+
+/**
+ * Get the authorization header value for a provider.
+ */
+export function getAuthHeader(provider: string): string | undefined {
+  const auth = getAuth(provider);
+  if (!auth) return undefined;
+
+  if (auth.token) {
+    // Anthropic uses x-api-key header, not Authorization
+    return auth.token;
+  }
+  if (auth.apiKey) {
+    return auth.apiKey;
+  }
+  return undefined;
+}

package/src/config.ts

@@ -0,0 +1,220 @@
+/**
+ * FreeRouter Config — OpenClaw Plugin Edition
+ *
+ * Reads config from plugin API (plugins.entries.freerouter.config)
+ * instead of freerouter.config.json. Falls back to built-in defaults.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { logger } from "./logger.js";
+
+// ═══ Config Types ═══
+
+export type AuthConfig = {
+  type: "openclaw" | "env" | "file" | "keychain";
+  key?: string;
+  profilesPath?: string;
+  filePath?: string;
+  service?: string;
+  account?: string;
+};
+
+export type ProviderConfigEntry = {
+  baseUrl: string;
+  api: "anthropic" | "openai";
+  headers?: Record<string, string>;
+  auth?: AuthConfig;
+};
+
+export type TierMapping = {
+  primary: string;
+  fallback: string[];
+};
+
+export type ThinkingConfig = {
+  adaptive?: string[];
+  enabled?: { models: string[]; budget: number };
+};
+
+export type FreeRouterConfig = {
+  port: number;
+  host: string;
+  providers: Record<string, ProviderConfigEntry>;
+  tiers: Record<string, TierMapping>;
+  agenticTiers?: Record<string, TierMapping>;
+  tierBoundaries?: {
+    simpleMedium: number;
+    mediumComplex: number;
+    complexReasoning: number;
+  };
+  thinking?: ThinkingConfig;
+  auth: {
+    default: string;
+    [strategy: string]: unknown;
+  };
+  scoring?: Record<string, unknown>;
+};
+
+// ═══ Defaults ═══
+
+const DEFAULT_CONFIG: FreeRouterConfig = {
+  port: 18800,
+  host: "127.0.0.1",
+  providers: {
+    anthropic: {
+      baseUrl: "https://api.anthropic.com",
+      api: "anthropic",
+    },
+    "kimi-coding": {
+      baseUrl: "https://api.kimi.com/coding/v1",
+      api: "openai",
+      headers: { "User-Agent": "KimiCLI/0.77" },
+    },
+  },
+  tiers: {
+    SIMPLE:    { primary: "kimi-coding/kimi-for-coding", fallback: ["anthropic/claude-haiku-4-5"] },
+    MEDIUM:    { primary: "anthropic/claude-sonnet-4-5", fallback: ["anthropic/claude-opus-4-6"] },
+    COMPLEX:   { primary: "anthropic/claude-opus-4-6", fallback: ["anthropic/claude-haiku-4-5"] },
+    REASONING: { primary: "anthropic/claude-opus-4-6", fallback: ["anthropic/claude-haiku-4-5"] },
+  },
+  agenticTiers: {
+    SIMPLE:    { primary: "kimi-coding/kimi-for-coding", fallback: ["anthropic/claude-haiku-4-5"] },
+    MEDIUM:    { primary: "anthropic/claude-sonnet-4-5", fallback: ["anthropic/claude-opus-4-6"] },
+    COMPLEX:   { primary: "anthropic/claude-opus-4-6", fallback: ["anthropic/claude-haiku-4-5"] },
+    REASONING: { primary: "anthropic/claude-opus-4-6", fallback: ["anthropic/claude-haiku-4-5"] },
+  },
+  thinking: {
+    adaptive: ["claude-opus-4-6", "claude-opus-4.6"],
+    enabled: { models: ["claude-sonnet-4-5"], budget: 4096 },
+  },
+  auth: {
+    default: "openclaw",
+    openclaw: {
+      type: "openclaw",
+      profilesPath: "~/.openclaw/agents/main/agent/auth-profiles.json",
+    },
+  },
+};
+
+// ═══ Singleton ═══
+
+let _config: FreeRouterConfig | null = null;
+let _configSource: string = "defaults";
+
+/**
+ * Deep-merge source into target (source wins). Arrays are replaced, not merged.
+ */
+function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const sv = source[key];
+    const tv = target[key];
+    if (sv && typeof sv === "object" && !Array.isArray(sv) && tv && typeof tv === "object" && !Array.isArray(tv)) {
+      result[key] = deepMerge(tv as Record<string, unknown>, sv as Record<string, unknown>);
+    } else {
+      result[key] = sv;
+    }
+  }
+  return result;
+}
+
+/**
+ * Load config from plugin config object (passed from OpenClaw plugin API).
+ * Merges with defaults — user only needs to specify overrides.
+ */
+export function loadConfigFromPlugin(pluginConfig: Record<string, unknown>): FreeRouterConfig {
+  _config = deepMerge(
+    DEFAULT_CONFIG as unknown as Record<string, unknown>,
+    pluginConfig as unknown as Record<string, unknown>,
+  ) as unknown as FreeRouterConfig;
+  _configSource = "plugin";
+  logger.info("Loaded config from OpenClaw plugin");
+  logger.info(`  Providers: ${Object.keys(_config.providers).join(", ")}`);
+  logger.info(`  Tiers: ${Object.keys(_config.tiers).join(", ")}`);
+  return _config;
+}
+
+/**
+ * Load config from file (standalone fallback).
+ */
+export function loadConfig(): FreeRouterConfig {
+  // Try file-based config as fallback
+  const paths = [
+    process.env.FREEROUTER_CONFIG,
+    join(process.cwd(), "freerouter.config.json"),
+    join(homedir(), ".config", "freerouter", "config.json"),
+  ].filter(Boolean) as string[];
+
+  for (const p of paths) {
+    if (existsSync(p)) {
+      try {
+        const raw = readFileSync(p, "utf-8");
+        const fileConfig = JSON.parse(raw) as Partial<FreeRouterConfig>;
+        _config = deepMerge(DEFAULT_CONFIG as unknown as Record<string, unknown>, fileConfig as unknown as Record<string, unknown>) as unknown as FreeRouterConfig;
+        _configSource = p;
+        logger.info(`Loaded config from ${p}`);
+        return _config;
+      } catch (err) {
+        logger.error(`Failed to load config from ${p}:`, err);
+      }
+    }
+  }
+
+  logger.info("No config file found, using built-in defaults");
+  _config = { ...DEFAULT_CONFIG };
+  _configSource = "defaults";
+  return _config;
+}
+
+export function reloadConfig(): FreeRouterConfig {
+  _config = null;
+  return loadConfig();
+}
+
+export function getConfig(): FreeRouterConfig {
+  if (!_config) return loadConfig();
+  return _config;
+}
+
+export function getConfigPath(): string | null {
+  return _configSource === "defaults" ? null : _configSource;
+}
+
+export function getSanitizedConfig(): Record<string, unknown> {
+  const cfg = getConfig();
+  const sanitized = JSON.parse(JSON.stringify(cfg));
+  if (sanitized.auth) {
+    for (const [key, val] of Object.entries(sanitized.auth)) {
+      if (key === "default") continue;
+      if (val && typeof val === "object" && (val as any).profilesPath) {
+        (val as any).profilesPath = "***";
+      }
+    }
+  }
+  for (const prov of Object.values(sanitized.providers ?? {})) {
+    if ((prov as any).auth?.key) (prov as any).auth.key = "***";
+  }
+  return sanitized;
+}
+
+export function toInternalApiType(api: "anthropic" | "openai"): "anthropic-messages" | "openai-completions" {
+  return api === "anthropic" ? "anthropic-messages" : "openai-completions";
+}
+
+export function supportsAdaptiveThinking(modelId: string): boolean {
+  const cfg = getConfig();
+  const patterns = cfg.thinking?.adaptive ?? ["claude-opus-4-6", "claude-opus-4.6"];
+  return patterns.some(p => modelId.includes(p));
+}
+
+export function getThinkingBudget(modelId: string): number | null {
+  const cfg = getConfig();
+  const enabled = cfg.thinking?.enabled;
+  if (!enabled) return null;
+  if (enabled.models.some(m => modelId.includes(m))) return enabled.budget;
+  return null;
+}
+
+export { DEFAULT_CONFIG };

package/src/logger.ts

@@ -0,0 +1,32 @@
+/**
+ * ClawRouter Logger — minimal, zero-dep
+ */
+
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 } as const;
+type Level = keyof typeof LEVELS;
+
+let currentLevel: Level = "info";
+
+export function setLogLevel(level: Level) {
+  currentLevel = level;
+}
+
+function log(level: Level, ...args: unknown[]) {
+  if (LEVELS[level] < LEVELS[currentLevel]) return;
+  const ts = new Date().toISOString().slice(11, 23);
+  const prefix = `[${ts}] ${level.toUpperCase().padEnd(5)}`;
+  if (level === "error") {
+    console.error(prefix, ...args);
+  } else if (level === "warn") {
+    console.warn(prefix, ...args);
+  } else {
+    console.log(prefix, ...args);
+  }
+}
+
+export const logger = {
+  debug: (...args: unknown[]) => log("debug", ...args),
+  info: (...args: unknown[]) => log("info", ...args),
+  warn: (...args: unknown[]) => log("warn", ...args),
+  error: (...args: unknown[]) => log("error", ...args),
+};