OpenRouter — LLM Aggregator / Fallback Tier

OpenRouter is the Tier 2 LLM fallback path for non-Anthropic models and Anthropic outage scenarios in OpenClaw. It aggregates 300+ LLMs under a single OpenAI-compatible endpoint. All traffic routes through portkey via virtual key openrouter-fallback — never directly. A P0 stale key is in the security queue (see below). Read this hub before configuring any non-Anthropic model route or enabling OpenRouter fallback in a Portkey tier config.

Quick reference

Field	Value
Vendor	OpenRouter
URL	https://openrouter.ai
KB doc	API
Auth method	Bearer (API key)
Auth credential	op://Aurora/openrouter/api_key
Cred-proxy port	n/a (pending B1-B6 ratification per nemoclaw-audit-2026-05-03)
Webhook port	n/a
Webhook handler	n/a
Webhook dedup table	n/a
Tunnel path	n/a
Outbound API base	https://openrouter.ai/api/v1 (via Portkey)
Rate limits	200 RPM (free tier) / scales with credit balance on paid tier
Rate-limit action	429 → exponential backoff (3 retries), Discord ops alert; 402 → add credits alert
Cost	Pay-as-you-go; varies by model (e.g., anthropic/claude-sonnet-4-5: $3/$15 per 1M tokens)
Backup/recovery	Vendor-owned; multi-provider routing makes OpenRouter self-healing
Discord alert channel	ops
Drift cadence	weekly (security-audit-funnel.timer)
Status	production
Portkey virtual key	openrouter-fallback

⚠️ P0 SECURITY: Stale key — REVOCATION PENDING

Stale key sk-or-v1-275e42eac7... (truncated) documented in the security queue. This key was already rotated in master.env with a replacement, but the old key was NEVER revoked at the OpenRouter vendor dashboard (https://openrouter.ai/keys). The old key remains active at the vendor and could be used if leaked.

Required action: Log into https://openrouter.ai/keys → find key with prefix sk-or-v1-275e42eac7 → delete/revoke it. Already in security queue — do NOT use or log this key further. Rotation pending per feedback_no_plaintext_creds and G-NO-PLAINTEXT-CREDS gate.

Reference: 1password for key rotation procedure using op CLI.

Components

• /home/opsadmin/.openclaw/portkey-proxy/proxy.js — MODEL_CONFIGS maps non-Anthropic models → openrouter-fallback virtual key; isAnthropicModel check gates max-plan shortcut and falls through to Portkey cloud path for OpenRouter-routed models
• [[sources/kb/openrouter/API]] — full endpoint reference; model naming (provider/model-name), fallback routing, rate limits, cost tracking (last_verified: 2026-03-04)
• Portkey virtual key openrouter-fallback — resolves to op://Aurora/openrouter/api_key in Portkey dashboard
• Dashboard: https://openrouter.ai/activity — usage, generation stats, key management

How it’s used

• Trigger condition: An agent requests a non-Anthropic model (e.g., openai/gpt-4o, google/gemini-2.0-flash, deepseek/deepseek-r1) OR Anthropic API is unreachable and Portkey tier config specifies OpenRouter as fallback
• Workflow: proxy.js → isAnthropicModel = false → MODEL_CONFIGS[model] → Portkey virtual key openrouter-fallback → OpenRouter /api/v1/chat/completions → upstream provider
• Model naming: OpenRouter uses provider/model-name format (e.g., anthropic/claude-sonnet-4-5); stripProviderPrefix() in proxy.js strips the prefix before passing to Portkey
• Agents involved: Any agent requesting a non-Anthropic model; primarily used for research, cost-testing, and fallback scenarios
• Failure mode: 402 → balance exhausted → Discord ops alert; 429 → rate limited → backoff; 502 → provider unavailable → OpenRouter auto-routes to next provider in fallback chain
• Success criteria: Response matches OpenAI completion format; tool_calls row written to Supabase (CHOKEPOINT-1); latency < 30s for non-streaming calls

Data flow: non-Anthropic model routing

Agent request (model: "openai/gpt-4o")
  → proxy.js port :18900
  → isAnthropicModel = false
  → MODEL_CONFIGS["gpt-4o"] or DEFAULT_CONFIG
  → Portkey /v1/chat/completions (VK: openrouter-fallback)
  → OpenRouter /api/v1/chat/completions
  → OpenAI (or Anthropic/Google/etc. via OpenRouter provider routing)
  → response streamed back through Portkey → proxy.js → agent
  → tool_calls row written to Supabase (CHOKEPOINT-1)

Cross-links

Agents that touch this

• _summary — may request non-Claude models for research tasks
• _summary — research agent; uses various models for intel gathering
• _summary — kimi-for-coding pattern routes through OpenRouter or Moonshot-Kimi path

Skills that invoke this

• acq-analyze — may use cheaper models via OpenRouter for bulk conversation analysis
• il-marketplace-pull — enrichment pass may use non-Anthropic models

Plans that govern this

• vendor-deep-audit-comprehensive-2026-05-02 — OpenRouter is in Tier 1 vendor audit; 12 OSIL vendor rows reference OpenRouter routing
• nemoclaw-audit-2026-05-03 — B1-B6 ratification determines cred-proxy eligibility
• openclaw-fragmentation-fix-2026-05-01 — G-NO-PLAINTEXT-CREDS gate: stale key revocation is a compliance obligation

Feedback rules

• feedback_no_plaintext_creds — sk-or-v1-275e42eac7... must be revoked; current key as op://Aurora/openrouter/api_key
• feedback_credentials_repeat_exposure — do NOT log or print the stale key; treat as still-active until confirmed revoked
• feedback_always_redact_grep_output — if grepping master.env, redact the OR key from output
• feedback_chokepoint_principle — all OpenRouter calls must write tool_calls row per CHOKEPOINT-1
• feedback_dual_write_required — G-DUAL-WRITE; OpenRouter responses must write to both Portkey observability and Supabase tool_calls
• feedback_probe_before_execute — check /api/v1/auth/key balance before enabling high-volume routes
• feedback_source_master_env_before_checking — master.env is single source of truth for current (rotated) key

KB / source docs

• API — full API reference: endpoints, model naming, provider routing, rate limits, cost tracking (last_verified: 2026-03-04)

System maps

• request-lifecycle — non-Anthropic model path (falls through from isAnthropicModel = false)
• ports-topology — Portkey :18900 as the single routing surface

Related: LLM provider tier cluster

Anchor: portkey

Member	Role
portkey	Anchor; CHOKEPOINT-1; routes to OpenRouter via openrouter-fallback VK
anthropic	Primary tier (Tier 1); OpenRouter is Tier 2 fallback when Anthropic unavailable
openrouter	This hub — Tier 2 aggregator; 300+ models, fallback routing
moonshot-kimi	Tier 2 specialty; Kimi K2 for reasoning/coding; separate VK moonshot-kimi-84f4a1
voyage	Embedding tier; separate from LLM routing; Memory/embeddings cluster

Open issues / TODOs

• P0: Revoke stale key sk-or-v1-275e42eac7... at https://openrouter.ai/keys — not yet done
• cred-proxy-eligible: pending — will resolve after B1-B6 ratification per nemoclaw-audit-2026-05-03
• OpenRouter fallback in Portkey tier configs: verify which tier configs actually include openrouter-fallback as a target — run grep -r openrouter /home/opsadmin/.openclaw/portkey-proxy/
• Credit balance monitoring: no automated alert configured; add GET /api/v1/auth/key balance check to tool-calls-health-check.js

Recent activity

• 2026-05-03: hub created (W2-S7); P0 stale key flag documented
• Key rotated in master.env (date unknown); old key NOT revoked at vendor
• 2026-03-04: KB doc sources/kb/openrouter/API.md last verified