NadirClaw is a source-available, self-hostable LLM router and AI cost optimizer, developed by the Nadir team, and is the self-hosted core of the hosted Nadir Pro. Its goal is to route each prompt to the cheapest model that can reliably answer it while ensuring answer quality, and to verify the output, escalating to a stronger model only when necessary.
Purpose and Positioning NadirClaw is aimed at developers and teams who want to reduce LLM API costs while maintaining answer quality. It runs as an OpenAI-compatible proxy and can be used by Claude Code, Cursor, Continue, Aider, Windsurf, Codex, OpenClaw, Open WebUI, and any client compatible with the OpenAI interface. It runs locally, API keys do not leave the user's machine, and it routes directly to each provider without going through a third-party proxy.
Main Capabilities Routing: Uses a ~10ms sentence embedding classifier to predict the smallest model capable of answering, and preferentially sends to that model. Routing modifiers (such as agent tool loops, reasoning markers, visual content, long context) can override the score and force the use of a stronger tier. Verification: Before returning, scores the cheap model's answer using quality heuristics (refusal to answer, truncation, JSON format failure, etc.). Escalation: If the answer falls below the acceptance threshold (τ = 0.80), automatically escalates to the next best model. Classifier: Optional binary (default, ~10ms centroid classifier) or distilbert (three-class fine-tuned DistilBERT, natively predicting simple/mid/complex), selected via NADIRCLAW_COMPLEXITY_ANALYZER. Tiered routing: Supports three tiers: simple / mid / complex, with configurable thresholds (NADIRCLAW_TIER_THRESHOLDS), and NADIRCLAW_MID_MODEL can be set to provide a middle tier. N-tier YAML configuration: One classification header supports any number of tiers; the default configuration n2_default.yaml is a two-tier cascade, switchable via NADIRCLAW_TIERS_PROFILE, and custom YAML configurations can be hot-reloaded within 30 seconds. Cascade rules engine: Declarative YAML rules implement per-prompt overrides, such as force_escalate, set_threshold, force_cheap, set_max_tokens, supports hot reload. Agent task detection: automatically detects tool use, multi-step loops, and agent system prompts, forcing the use of complex models. Reasoning detection: identifies prompts that require chain-of-thought, routing to reasoning-optimized models. Vision routing: automatically detects image content in messages, routing to vision-capable models (GPT-4o, Claude, Gemini). Routing configuration: auto, eco, premium, free, reasoning, allowing cost/quality strategy selection per request. Model aliases: use short names like sonnet, flash, gpt4 instead of full model IDs. Session persistence: pins the model for multi-turn conversations, avoiding mid-conversation switching. Context window filtering: automatically switches to a model with a larger context window when the conversation is too long. Fallback chain: when a model fails (429, 5xx, timeout), falls back sequentially along a configurable chain until success. Streaming support: full SSE streaming, compatible with streaming clients such as OpenClaw and Codex. Native Gemini support: directly calls Gemini models via the Google GenAI SDK. OAuth login: use nadirclaw auth <provider> login to use a subscription without an API key. Multi-provider: supports Gemini, OpenAI, Anthropic, Ollama, and any provider supported by LiteLLM. OpenAI-compatible API: /v1/chat/completions endpoint, can replace any tool compatible with the OpenAI chat completions API. Anthropic-compatible API: /v1/messages endpoint, letting Anthropic-native clients such as Claude Code route through NadirClaw, with byte-for-byte streaming forwarding. Request reporting: nadirclaw report provides per-model and per-day cost breakdowns, anomaly flags, filtering, latency statistics, tier breakdowns, and token usage. Log export: nadirclaw export --format csv|jsonl --since 7d for offline analysis. Raw logs: optional --log-raw captures full request/response content for debugging and replay. Prometheus metrics: built-in /metrics endpoint, including request counts,latency histograms, token/cost totals, cache hits, and fallback tracking. OpenTelemetry tracing: optional distributed tracing, following GenAI semantic conventions. Cost savings calculator: nadirclaw savings shows the amount saved and monthly projections. Spend tracking and budgets: real-time per-request cost tracking, supports daily/monthly budget limits, alerts via nadirclaw budget, with optional webhook and stdout notifications. Prompt caching: in-memory LRU cache for identical chat completions, skipping redundant LLM calls, with configurable TTL and maximum size. Live dashboard: nadirclaw dashboard terminal interface, or visit http://localhost:8856/dashboard to view the Web UI. GitHub Action: doramirdor/nadirclaw-action for CI/CD pipelines.
Usage Installation: a recommended one-line install command clones the repository to ~/.nadirclaw, creates a virtual environment, installs dependencies, and adds nadirclaw to PATH; running it again updates. You can also install from source. Setup: run the interactive setup wizard nadirclaw setup, choose a provider, enter an API key, and select a model for each routing tier. Then start the router with nadirclaw serve, which by default listens on http://localhost:8856，默认使用 Gemini 3 Flash handles simple requests, OpenAI Codex handles complex requests. If setup is skipped, serve will prompt to run it on first startup. Configuration: Load configuration from ~/.nadirclaw/.env, falling back to .env in the current directory if it does not exist. Credential provision order is: OpenClaw stored token, NadirClaw stored credentials, environment variables. On shared servers, environment variables can be prioritized via environment variables. Docker: You can run NadirClaw + Ollama fully locally at zero cost; the container listens on all interfaces, NADIRCLAW_AUTH_TOKEN must be set, and clients send it as Authorization: Bearer <token>. NadirClaw can also be run separately.
Use cases Suitable for developers and teams who want to reduce LLM API costs, need self-hosted routing, use multiple model providers, or want to optimize costs without changing existing OpenAI-compatible clients. In a typical coding session, 60-70% of prompts are relatively simple and can be handled by models that cost 10-20 times less.
Limitations NadirClaw is licensed under PolyForm Noncommercial 1.0.0; it is source-available rather than open source and is limited to non-commercial use. Commercial use requires the hosted Nadir Pro version. Classifier accuracy differs from Nadir Pro's trained classifier + DeBERTa verifier; NadirClaw uses a simpler binary centroid classifier, trading some accuracy for zero training cost. The RouterBench data in the documentation is a reference to assist in studying the upper bound, not a prediction of production performance or savings. Nadir has not published general production savings or quality percentages until measured on customer traffic with outcome labels. The DistilBERT classifier requires downloading an approximately 256MB model on first use; if the download fails, it falls back to the binary classifier. The Morph remote classifier is strictly optional and requires MORPH_API_KEY; on failure it falls back to the local binary classifier.
