- name
- openrouter-connect
- description
- >
OpenClaw — OpenRouter Free Model Skill
OpenClaw helps you:
- Discover all currently-free OpenRouter models at runtime
- Select one using a ranked preference list (fallback chain)
- Proxy a query live through the chosen model right in this conversation
- Scaffold production-ready Python or TypeScript code that does the same
Step 0 — Read the API key
Look for OPENROUTER_API_KEY in this priority order:
- Project
.env—./relative to the user's current working directory - Global
~/.env— the user's home directory - Shell environment — already exported in the current shell session
Use the helper script to resolve this:
python3 /home/claude/openrouter-connect/scripts/resolve_key.pyIf no key is found, tell the user and show them the quick-start box:
No key found. Get a free key at https://openrouter.ai/keys then add it to.env: ``OPENROUTER_API_KEY=sk-or-...``
Step 1 — Discover free models
Run the discovery script to fetch and cache the free model list:
python3 /home/claude/openrouter-connect/scripts/discover_models.py [--refresh]This calls GET https://openrouter.ai/api/v1/models (no auth required) and filters for models where both pricing.prompt == "0" and pricing.completion == "0".
The script outputs a JSON array ranked by the default preference list (see references/model_preferences.md for how ranking works and how to customise it).
Pass --refresh to bypass the 1-hour local cache.
Step 2 — Select a model (ranked fallback chain)
Read references/model_preferences.md for the full preference system.
Quick summary:
- The user's explicit ranked list is tried first (index 0 = highest priority)
- If a listed model isn't free right now, it's skipped
- If no listed model is available, fall back to the auto-ranked free pool
- Auto-ranking scores by: context window (weight 0.4), recency (0.3), provider reputation (0.3)
To ask the user for their preference list, show them the discovered models and say:
"Here are the free models I found. Would you like to rank your favourites, or should I pick the best one automatically?"
Step 3a — Proxy a query live
Once a model is selected, call it directly using the script:
python3 /home/claude/openrouter-connect/scripts/proxy_query.py \
--model "mistralai/mistral-7b-instruct:free" \
--prompt "Your question here"Stream the response back to the user and note which model was used.
If the model returns a 429 (rate limit) or 5xx, automatically retry with the next model in the ranked list. Log which model was tried and why it was skipped.
Step 3b — Scaffold code for the user
Read the appropriate template from references/:
- Python:
references/python_template.md - TypeScript / JS:
references/typescript_template.md
Fill in:
- The selected model ID
.envloading boilerplate (checks./then~/)- The fallback/retry loop
- A working
main()example with the user's actual prompt if they provided one
Always include inline comments explaining the fallback logic.
Edge cases & notes
| Situation | Behaviour |
|---|---|
| Model mid-list becomes paid | Skip it, log a warning, continue down the list |
| All ranked models unavailable | Fall back to auto-ranked free pool |
| No free models found at all | Tell the user — OpenRouter's free tier may be down |
| Key found but invalid (401) | Prompt user to check the key; show the OpenRouter keys URL |
| User provides a model not in the free list | Warn them it may incur cost; ask to confirm |
| Streaming not supported by model | Fall back to non-streaming request silently |
Reference files
| File | When to read |
|---|---|
references/model_preferences.md | Ranking algorithm, customisation, default weights |
references/python_template.md | Generating Python code |
references/typescript_template.md | Generating TS/JS code |