model-selector

Model Selector

FastAPI dashboard for browsing and editing the model/provider config in ~/.openclaw/openclaw.json.

It is intentionally small:

• canonical config stays in /home/lucky/.openclaw/openclaw.json
• provider snapshots are cached locally under data/model-cache/
• alias edits land in agents.defaults.models.<provider/model>.alias
• the server runs on port 3300

What it shows

• configured models from the canonical OpenClaw config
• live provider catalogs from OpenAI, Groq, and OpenRouter
• aliases, reasoning flags, context window, max tokens, and provider metadata when present
• missing capabilities as —, rather than guessing

Files That Matter

• model_selector/main.py - FastAPI app and API routes
• model_selector/config.py - canonical config read/write logic
• model_selector/providers.py - provider adapters and config serialization
• model_selector/service.py - dashboard state assembly
• model_selector/cache.py - local JSON snapshot cache
• run.sh - start the app
• killserver.sh - clear stale listeners on port 3300
• restart.sh - kill then start
• tests.sh - run the test suite

Quick Start

# Create a local virtualenv and install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Configure API keys if you want live provider catalogs
cp .env.example .env

# Start the dashboard
./run.sh

Open http://localhost:3300.

Configuration

The app reads these environment variables:

Variable	Default	Purpose
OPENCLAW_CONFIG_PATH	/home/lucky/.openclaw/openclaw.json	Canonical config file
MODEL_SELECTOR_PORT	3300	Web server port
MODEL_SELECTOR_HOST	0.0.0.0	Bind host
MODEL_SELECTOR_REFRESH_INTERVAL	1800	Live provider refresh interval, in seconds
MODEL_SELECTOR_CACHE_DIR	data/model-cache	Local JSON snapshot directory
OPENAI_API_KEY	unset	OpenAI live catalog access
GROQ_API_KEY	unset	Groq live catalog access
OPENROUTER_API_KEY	unset	OpenRouter live catalog access

The config schema is intentionally narrow:

{
  "models": {
    "providers": {
      "openai": {
        "models": [
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 16000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "models": {
        "openai/gpt-4o": {
          "alias": "my-favorite"
        }
      }
    }
  }
}

API

• GET / - dashboard UI
• GET /api/state - full dashboard state
• GET /api/config - config path and configured models
• POST /api/alias - update alias for a configured model
• POST /api/config/models/add - add a provider model to config
• POST /api/config/models/delete - remove a configured model
• POST /api/refresh - force a live provider refresh

Testing

Use the repo-local test runner:

bash tests.sh

That script uses .venv when present and falls back to python3 -m pytest -q if not.

The tests use temporary config fixtures and do not touch the live ~/.openclaw/openclaw.json.

Notes

• Runtime cache files under data/model-cache/ are local-only and ignored by git.
• The dashboard keeps the configured-model view separate from provider catalogs on purpose.
• OpenRouter config writes only include parameters that the dashboard knows are valid.