Smart Router V3

Intent-based AI model router that classifies requests and routes to the best provider. Auto-discovers OpenClaw providers and model lists from openclaw.json,...

Security Scan

The skill generally matches an intent-based model router, but there are packaging and scope inconsistencies (missing service files, hardcoded absolute imports, undeclared env usage, and the ability to start user services) that warrant caution before installing.

Purpose & Capability

The name, description, and code align: the Python router and helper JS implement provider discovery, intent scoring, and OpenAI-compatible routing. Features like mapping Anthropic -> local Dario, discovering providers from ~/.openclaw/openclaw.json, and persisting latency stats to ~/.cache are coherent with a router. However, the SKILL.md refers to systemd unit files (systemd/smart-router.service and .env.example) that are not present in the provided file manifest, and the JS helper imports OpenClaw from an absolute path under /home/umbrel/.nvm which is host-specific and unlikely to work as-is. These packaging gaps are inconsistent with the installation instructions.

Instruction Scope

Runtime instructions and code read ~/.openclaw/openclaw.json, resolve ${ENV_VAR} placeholders, persist latency to ~/.cache/smart-router-v3/latency-stats.json, and may call external provider endpoints — all expected. Concern: SKILL.md tells the user to copy systemd/unit files that do not appear in the skill's files, so following the instructions as-is would fail or lead the user to supply their own units. The router also invokes systemctl to check/start a Dario service and runs subprocesses; these operations alter user-level services and can start other binaries (dario), which expands the runtime scope beyond passive routing.

Install Mechanism

There is no install spec (instruction-only), which is low risk in the sense that nothing is automatically downloaded. The skill includes source files (router.py and an mjs helper) but no fetched archives or remote installs are present in the package. That said, SKILL.md instructs copying systemd units that are missing from the package, implying the package is incomplete rather than installing from unknown URLs.

Credentials

The registry metadata lists no required env vars, but the code and SKILL.md rely on many SMART_ROUTER_* environment variables (timeouts, paths, SMART_ROUTER_DISABLED_PROVIDERS, SMART_ROUTER_DARIO_*, SMART_ROUTER_OPENCLAW_AGENT_ID, etc.) and also read provider API keys from ~/.openclaw/openclaw.json (including resolving ${ENV_VAR} placeholders). The skill therefore accesses environment variables and potentially provider API keys without declaring them — this is a transparency/privilege concern because secrets in env or openclaw.json would be used and potentially transmitted to external providers (which is expected for a router but should be explicit).

Persistence & Privilege

The skill is not always-enabled and is user-invocable by default. It persists empirical latency stats to ~/.cache and expects to run as a user systemd service. It also attempts to start a user-level Dario service via systemctl and checks for a 'dario' binary; ability to start/stop user services expands operational privilege (user-level only) and can change systemd-managed processes. This behavior is explainable by Anthropic compatibility needs but should be considered before enabling the service on a machine.

What to consider before installing

This skill mostly does what it claims, but there are several red flags you should address before installing: (1) The SKILL.md references systemd unit and env example files that are not included — ask the author for the missing files or inspect/craft your own service unit before enabling. (2) Inspect router.py and openclaw_gateway_agent.mjs yourself: the router will read ~/.openclaw/openclaw.json and environment variables (including API keys if you use ${ENV_VAR} placeholders) and will forward requests to external providers — only install if you trust those providers and are comfortable with prompts being sent externally. (3) The JS helper imports OpenClaw from an absolute path under /home/umbrel/.nvm; this is host-specific and likely broken on other systems — verify the helper and adjust imports or PATH as needed. (4) Because the service may start a user-level Dario systemd unit and run subprocesses, only enable the service if you understand and consent to it managing user services. If anything is unclear, request the missing files or a release tarball from the repository referenced in _meta.json (https://github.com/earlvanze/smart-router-v3), test the code in an isolated environment, and review any systemd unit before enabling it.

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