Smart Router V3

HTTP server on :8788 that routes OpenAI-compatible chat requests to the optimal provider based on intent classification.

Active Providers

Providers are discovered from ~/.openclaw/openclaw.json at startup.

Rules:

• skips the router's own smart-router provider entry to avoid recursion
• resolves ${ENV_VAR} values for baseUrl and apiKey
• includes OpenClaw gateway openai-codex as a virtual provider when the auth profile exists
• recognizes Google Gemini providers from generativelanguage.googleapis.com
• auto-discovers Google models when the provider exists but models is empty in openclaw.json
• normalizes anthropic or Anthropic-hosted anthropic-messages providers onto the local Dario proxy at localhost:3456
• starts the Dario user service when Anthropic compatibility is needed and the service is not already running
• supports temporary provider suppression via SMART_ROUTER_DISABLED_PROVIDERS=name1,name2

GET /health shows:

• configured: all discovered providers
• providers: reachable providers with model lists
• disabled: providers suppressed by env

Routing Logic

The router no longer uses a hardcoded provider whitelist.

Flow:

• detect intent from the latest user message
• estimate complexity from prompt length
• score every reachable provider/model pair from openclaw.json
• for GENERAL, blend static heuristics with persisted empirical latency stats by provider and model
• rank candidates by API type, model-name hints, complexity, and measured latency
• attempt the top SMART_ROUTER_MAX_PROVIDER_ATTEMPTS candidates in order

Intent scoring is generic, for example:

• code and analysis strongly favor Anthropic/OpenAI-style reasoning models
• general/realtime requests prefer fast direct providers first
• general traffic learns from real successful request latency over time, with light exploration for cold providers/models
• complex prompts boost larger reasoning models and penalize mini/haiku-class models

Intent is detected by keyword matching on the latest user message. Complexity is estimated by word count.

API

• GET /health — JSON with reachable providers, configured providers, and disabled providers
• POST /v1/chat/completions — OpenAI-compatible; routes automatically

Notes

• openai-codex is kept as an optional bridge, not a required first hop.
• Anthropic compatibility is provided through Dario, so anthropic can stay in openclaw.json while routing locally through dario.
• The repo systemd unit is template-style and expects local machine values in ~/.config/smart-router/smart-router.env.
• Empirical latency memory is persisted at ~/.cache/smart-router-v3/latency-stats.json by default.
• When the OpenClaw gateway model-set path is unhealthy, the helper falls back to running without provider/model overrides instead of failing hard.
• If any provider starts misbehaving, suppress it with SMART_ROUTER_DISABLED_PROVIDERS instead of editing the router.
• GitHub workflows now include CI syntax checks and CodeQL analysis for Python + JavaScript.
• See BRANCH_PROTECTION.md for the exact required-check setup on GitHub.

Install

Install the user service from the repo copy:

mkdir -p ~/.config/systemd/user ~/.config/smart-router
cp systemd/smart-router.service ~/.config/systemd/user/smart-router.service
cp systemd/smart-router.env.example ~/.config/smart-router/smart-router.env
# edit ~/.config/smart-router/smart-router.env for your machine
systemctl --user daemon-reload
systemctl --user enable --now smart-router.service

Notes:

• the repo unit is now env-driven and does not hardcode your home path, Node version, or workspace location
• set SMART_ROUTER_HOME to the actual repo path on your machine
• optionally set SMART_ROUTER_PATH_PREFIX if your Python, Node, or Dario bins are not already on PATH

If an Anthropic provider is detected and Dario is not installed yet, install Dario first:

• GitHub: https://github.com/askalf/dario

Service

systemctl --user status smart-router
systemctl --user restart smart-router
journalctl --user -u smart-router -f   # live logs