OpenClaw — OpenRouter Free Model Skill#

OpenClaw helps you:

1. Discover all currently-free OpenRouter models at runtime
2. Select one using a ranked preference list (fallback chain)
3. Proxy a query live through the chosen model right in this conversation
4. 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:

1. Project .env — ./ relative to the user's current working directory
2. Global ~/.env — the user's home directory
3. Shell environment — already exported in the current shell session

Use the helper script to resolve this:

bash

python3 /home/claude/openrouter-connect/scripts/resolve_key.py

If 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:

text

OPENROUTER_API_KEY=sk-or-...

---

Step 1 — Discover free models#

Run the discovery script to fetch and cache the free model list:

bash

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:

bash

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
• .env loading 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#

SituationBehaviourModel mid-list becomes paidSkip it, log a warning, continue down the listAll ranked models unavailableFall back to auto-ranked free poolNo free models found at allTell the user — OpenRouter's free tier may be downKey found but invalid (401)Prompt user to check the key; show the OpenRouter keys URLUser provides a model not in the free listWarn them it may incur cost; ask to confirmStreaming not supported by modelFall back to non-streaming request silently

---

Reference files#

FileWhen to readreferences/model_preferences.mdRanking algorithm, customisation, default weightsreferences/python_template.mdGenerating Python codereferences/typescript_template.mdGenerating TS/JS code