Sage Router

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 mostly does what its README promises (a local model router) but its declared metadata omits a number of sensitive behaviors: it reads user config and credential stores (openclaw/.env, browser cookie DB), will attempt to unlock and read Bitwarden via the bw CLI, and persists local encrypted cookies — behaviors that are disproportionate to a simple router and are not surfaced in the registry metadata.

Purpose & Capability

The SKILL.md and code implement an intent-based router that auto-discovers providers from ~/.openclaw/openclaw.json — that part is coherent. However the registry metadata claims no required env vars or config paths while the SKILL.md and code rely on and read many local config paths (~/.openclaw, ~/.dario, ~/.config/sage-router, ~/.cache/sage-router). The code also contains additional functionality (Grok SSO proxy, Bitwarden access, autostarting bundled services like Ollama/Dario) that go beyond a minimal router and require access to local secrets/configs. This mismatch between declared requirements and actual behavior is a concern.

Instruction Scope

SKILL.md instructs the router to discover providers from ~/.openclaw/openclaw.json and to persist latency stats to ~/.cache. The bundled grok_sso_proxy.py (documented separately) will read browser cookie DBs or cookie JSON files to proxy SSO, and its code will call the bw CLI to unlock/read Bitwarden items if enabled. The router also loads .env files into process environment. These instructions and code direct the agent to read user credentials and local secrets (browser cookies, Bitwarden items, .env API keys), which is broader than a simple request router unless the user explicitly wants SSO/cookie-based proxies.

Install Mechanism

There is no registry install spec, but the repo includes Docker compose files and scripts. The recommended installation paths (docker-compose, systemd) are standard and the image is referenced via a well-known host (ghcr.io) in docs. There are no remote downloads from ad-hoc servers in the install instructions. That reduces install risk, but the package contains many executable scripts that will run locally (python scripts, shell entrypoint, launching other binaries like ollama or dario), so review is required before running.

Credentials

Registry metadata declared no required env vars, yet SKILL.md and code require and use several environment variables and config files: SAGE_ROUTER_HOME (documented as required), SAGE_ROUTER_DISABLED_PROVIDERS, OPENCLAW_GATEWAY_TOKEN, and the router loads ~/.openclaw/.env and other env files automatically. The Grok SSO proxy will attempt to use Bitwarden (bw CLI) and environment variables (BW_SESSION or BW_PASSWORD) to unlock and retrieve stored credentials. Reading browser cookie DBs and automatically loading .env values is disproportionate unless the user explicitly consents to SSO and credential access.

Persistence & Privilege

The service persists data to user-local paths (e.g., ~/.cache/sage-router/latency-stats.json and an encrypted cookie file under ~/.config/sage-router by default). It may create an encryption key file with restrictive permissions for cookie storage. always:false (no forced always-on). The persistence and file creation are expected for a long-running router, but combined with secret access (cookies/Bitwarden/.env) increases the sensitivity of what is stored and where — you should verify those paths and review files created by the service.

What to consider before installing

Before installing or running this skill, be aware of these specific concerns and take mitigations: 1) Metadata vs reality — the registry lists no required env vars, but the skill reads ~/.openclaw/openclaw.json, ~/.openclaw/.env, ~/.dario, browser cookie DBs, and writes to ~/.cache and ~/.config/sage-router. Expect the service to load API keys and tokens from those locations. 2) Grok SSO proxy behavior — if you enable or run the bundled grok_sso_proxy.py it will attempt to read cookies from a browser cookie DB or cookie JSON and, by default, will try to access Bitwarden via the bw CLI to retrieve stored credentials. If you do not want this, set GROK_SSO_BITWARDEN_ENABLED=false or avoid running the proxy. 3) Least-privilege installation — run the router in an isolated environment (dedicated VM or container) and avoid bind-mounting your entire home directory into the container; only mount the minimal config files you explicitly trust. 4) Audit inputs — inspect openclaw.json, any .env files, provider-profiles.json, and grok_sso_proxy.py before enabling the service. Remove or disable code paths you don't need (SSO proxy, Bitwarden integration, autostart of Ollama/Dario). 5) Network exposure — by default the service listens on localhost:8788; do not expose it publicly unless you intend to and have proper auth/reverse proxy controls. 6) If you need further assurance, ask the skill author to: (a) declare required env vars and config paths in registry metadata, (b) disable Bitwarden access by default, and (c) document exactly what files it reads/writes. If you cannot audit or restrict filesystem and CLI access, treat this skill as higher-risk and run it only in an isolated environment.

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

Endpoints

• POST /v1/chat/completions — OpenAI-compatible; routes automatically
• POST /v1/messages — Anthropic Messages API compatible; translates to/from OpenAI format internally
• GET /health — Provider status, model lists, routing debug

Any Anthropic-compatible tool (Cursor, Aider, Claude Code, Zed, Continue, OpenHands) can point at http://localhost:8788 as the API base URL. Both streaming and non-streaming are supported.

Active Providers

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

Rules:

• skips the router's own sage-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; in Docker, the image bundles @askalf/dario and autostarts dario proxy when credentials are mounted at /root/.dario
• supports temporary provider suppression via SAGE_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 does not perform mid-stream switching. Once a request is sent to a provider, the full response is returned or the attempt fails. If it fails, the next candidate in the chain is tried sequentially. There is no partial-output fallback or streaming handoff between providers.

Flow:

• detect intent from the latest user message
• estimate complexity from prompt length
• score every reachable (provider, model) pair globally — not per-provider — 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 SAGE_ROUTER_MAX_PROVIDER_ATTEMPTS candidates in order
• sage-router provider (the router itself, model auto) is scored as a low-priority recursive fallback, never preferred

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/sage-router/sage-router.env.
• Empirical latency memory is persisted at ~/.cache/sage-router/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 SAGE_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.
• provider-profiles.json includes a grok-sso template for the OpenClaw xAI auth plugin's local SuperGrok-backed proxy.

Install

Install the user service from the repo copy:

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

Notes:

• the repo unit is now env-driven and does not hardcode your home path, Node version, or workspace location
• set SAGE_ROUTER_HOME to the actual repo path on your machine
• optionally set SAGE_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 sage-router
systemctl --user restart sage-router
journalctl --user -u sage-router -f   # live logs

Docker production notes

• Docker image includes Node, Python, Sage Router, and @askalf/dario.
• Mount host Dario credentials as ~/.dario:/root/.dario for Anthropic-compatible Claude routing.
• Enable llama.cpp classifier sidecar with docker compose --profile classifier up -d and SAGE_ROUTER_INTENT_CLASSIFIER_ENABLED=1.
• Production classifier flags: SAGE_ROUTER_INTENT_CLASSIFIER_PROVIDER=llamacpp, SAGE_ROUTER_INTENT_CLASSIFIER_BASE_URL=http://llamacpp-classifier:8080, SAGE_ROUTER_INTENT_CLASSIFIER_MODEL=classifier.