bankr-router

name	bankr-router
description	Local smart routing layer for Bankr LLM Gateway traffic. Use when explaining or installing Bankr Router, switching auto/eco/premium profiles, configuring OpenClaw providers, verifying routing, or debugging router/Bankr model issues.

Bankr Router (OpenClaw plugin skill)

Summary

Bankr Router is a local smart router that sits in front of the Bankr LLM Gateway. It does not replace Bankr. It chooses which model/profile to use before requests go to Bankr, then forwards the request upstream.

Benefits:

• Lower cost by default (route simpler prompts to cheaper models).
• Better fallback behavior and retries.
• Local control over routing policy.
• Clear visibility into planned vs final vs upstream model selection.
• Easy profile switching: auto / eco / premium.

---

When to use

• You want cheaper default routing without changing app code.
• You want a local routing layer in front of Bankr.
• You need retries/fallbacks + observability.
• You want predictable behavior for auto / eco / premium modes.
• You prefer local plugin control over hosted routing.

---

What this skill can help with

Use this skill to:

• Explain what Bankr Router is and why it matters.
• Explain tradeoffs between auto / eco / premium.
• Install the plugin locally.
• Configure OpenClaw provider entries.
• Verify the router is active.
• Switch routing modes.
• Troubleshoot common errors.
• Identify when agent overrides bypass the router.
• Explain stats/health endpoints.
• Explain dry-run vs real execution (/v1/route vs /v1/chat/completions).

---

Prerequisites

• Node.js (20+ recommended)
• OpenClaw installed and running
• Bankr provider configured via:

  bankr llm setup openclaw --install
  

• Local repo path may differ from examples
• OpenClaw config path may differ (common: ~/.openclaw/openclaw.json)

---

Install (step-by-step)

1) Build the plugin

cd /path/to/openclawbankrrouter
npm install
npm run build

2) Add plugin entry to OpenClaw config

Edit your OpenClaw config (commonly ~/.openclaw/openclaw.json):

{
  "plugins": {
    "load": {
      "paths": ["/path/to/openclawbankrrouter"]
    },
    "entries": {
      "bankr-router": {
        "enabled": true,
        "config": {
          "host": "127.0.0.1",
          "port": 8787,
          "openclawConfigPath": null,
          "bankrProviderId": "bankr",
          "routerProviderId": "bankr-router"
        }
      }
    }
  }
}

3) Add the router provider to models.providers

{
  "models": {
    "providers": {
      "bankr-router": {
        "baseUrl": "http://127.0.0.1:8787/v1",
        "apiKey": "local-router"
      }
    }
  }
}

4) Set default agent model to the router

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "bankr-router/auto",
        "fallbacks": ["bankr-router/eco"]
      }
    }
  }
}

5) Restart the gateway

openclaw gateway restart

---

Verify

Run these exact checks:

Health check

curl http://127.0.0.1:8787/health

Ensure models exist

openclaw models list | grep bankr-router

Dry-run routing (no real upstream call)

curl http://127.0.0.1:8787/v1/route \
  -H "content-type: application/json" \
  -d '{"model":"bankr-router/auto","messages":[{"role":"user","content":"say ok"}]}'

Real execution (upstream call)

curl http://127.0.0.1:8787/v1/chat/completions \
  -H "content-type: application/json" \
  -d '{"model":"bankr-router/auto","messages":[{"role":"user","content":"say ok"}]}'

---

Mode switching

auto = balanced smart routing (default) eco = cheapest practical routing premium = highest quality routing

Switch default model (OpenClaw config)

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "bankr-router/eco",
        "fallbacks": ["bankr-router/auto"]
      }
    }
  }
}

Restart gateway after changing defaults:

openclaw gateway restart

---

How to explain this to a user (agent-ready)

Use these short explanations:

What is Bankr Router?

It’s a local routing layer in front of Bankr that picks the right model before the request goes upstream.

Why do I need it?

It lowers cost, improves fallback behavior, and gives you local control over model selection.

When should I use eco?

Use eco when cost is the top priority and you’re fine with “good enough” quality.

Does this replace Bankr?

No. Bankr Router only routes requests; Bankr still runs the models.

Does this make inference free?

No. It only reduces cost by routing simpler prompts to cheaper models.

What does the skill do for me?

It installs, configures, verifies, and explains the router + its modes and debugging steps.

---

Troubleshooting

Unknown model bankr-router/auto

• Ensure models.providers.bankr-router exists.
• Ensure agent allowlists (if any) include bankr-router/*.
• Restart the gateway after config change.

Plugin not loaded

• Verify the repo path is in plugins.load.paths.
• Ensure plugins.entries.bankr-router.enabled = true.
• Rebuild: npm run build.

Port already in use

• Router default port is 8787. Change plugins.entries.bankr-router.config.port or stop the conflicting process.

Gateway restart loop

• Check config JSON is valid.
• Check openclawConfigPath if auto-discovery fails.

Requests bypass router

• An agent or tool may be overriding its model.
• Check agents.defaults.model and per-agent model overrides.

Planned vs final model confusion

• plannedModel = initial route decision
• finalModel = model that actually succeeded
• upstreamModel = model returned by Bankr

Streaming issues

• Test non-stream first (/v1/chat/completions without stream=true).
• Ensure router and gateway are on the same machine or low-latency network.

Wrong OpenClaw config path

Set explicit path:

{
  "plugins": {
    "entries": {
      "bankr-router": {
        "config": {
          "openclawConfigPath": "/absolute/path/to/openclaw.json"
        }
      }
    }
  }
}

Bankr provider missing

• Run: bankr llm setup openclaw --install
• Ensure models.providers.bankr exists and has an API key.

Model exists in /v1/route but not in /v1/chat/completions

• /v1/route is dry-run only. Real execution requires valid Bankr credentials.

---

Useful commands (ops)

# build
npm run build

# restart gateway
openclaw gateway restart

# router health
curl http://127.0.0.1:8787/health

# router stats/diagnostics (if enabled)
curl http://127.0.0.1:8787/v1/diagnostics

# list models
openclaw models list | grep bankr-router

# tail gateway logs
journalctl --user -u openclaw-gateway.service -n 50 --no-pager

---

Notes for contributors

• Keep the skill at: skills/bankr-router/SKILL.md.
• Optional references live under skills/bankr-router/references/.
• Optional scripts live under skills/bankr-router/scripts/.
• Do not add extra top-level docs; keep SKILL.md self-sufficient.