---
name: use-openrouter
description: Route any OpenRouter task through the official OpenRouter MCP, bundled official OpenRouter skills, live official documentation, or the official REST API and SDKs. Use for OpenRouter model research, comparisons, reproducible experiments, inference, multimodal generation, analytics, account or key administration, integrations, debugging, authentication, updates, or first-time setup.
---

# Use OpenRouter

Use official OpenRouter capabilities in this order:

1. Use the bundled OpenRouter MCP server when it exposes the required operation. Its configured name is `openrouter` in Codex and `plugin:openrouter:openrouter` in Claude Code.
2. Follow the matching bundled official OpenRouter skill for specialized workflows.
3. Search live official docs with MCP `search-docs`; if MCP is unavailable, start from `https://openrouter.ai/docs/llms.txt` and the exact linked official page.
4. Use the official REST API or SDK only when MCP does not cover the operation. Confirm current request shapes against `https://openrouter.ai/openapi.json` when applicable.

Do not reimplement an official SDK, maintain a local model catalog, or rely on remembered model names, prices, limits, or capabilities when live official data is available.

Translate natural-language requests into the required workflow. Do not require the user to know model slugs, endpoint names, API request shapes, or which skill to invoke. Discover those details from live official sources, explain only decisions that affect cost, permissions, or results, and ask only for missing choices that materially change the operation.

## Sign in through MCP OAuth

When asked to initialize, set up, connect, authenticate, sign in, or log in to OpenRouter:

1. In Codex, run `codex mcp login openrouter`. In Claude Code, run `/mcp`, select the plugin-provided OpenRouter server, and follow the browser authentication flow.
2. Let the host open the official OpenRouter MCP OAuth flow and wait for the user to authorize it.
3. Report whether login completed. Do not inspect or configure `OPENROUTER_API_KEY`, `OPENROUTER_MANAGEMENT_API_KEY`, quotas, workspaces, or other account settings unless the user explicitly asks for those separately.

Treat these login requests as OAuth-only. Do not substitute MCP `ping` for the authentication flow and do not expand setup into API-key onboarding.

## Authenticate only when needed

- For initialize, setup, connect, authenticate, sign-in, or login requests, start the host-specific MCP authentication flow above directly.
- Prefer MCP OAuth for MCP-supported tasks. Do not ask for a general API key merely to use MCP.
- Before running an official skill or direct inference API call, check only whether `OPENROUTER_API_KEY` is present. Never print, echo, log, persist in the project, or include the value in tool output.
- If the key is absent, ask the user to create a dedicated, limited key at `https://openrouter.ai/keys`. Never ask them to paste it into chat.
- In the macOS Codex app, have the user run these commands themselves in Terminal:

```zsh
read -s "OPENROUTER_API_KEY?OpenRouter API key: "
launchctl setenv OPENROUTER_API_KEY "$OPENROUTER_API_KEY"
unset OPENROUTER_API_KEY
```

Tell the user to fully reopen Codex and start a new task afterward. To remove the login-session value, use `launchctl unsetenv OPENROUTER_API_KEY`.

- In Claude Code or Codex CLI, have the user inject the key through their shell or secret manager before launching a new agent session. When no secret manager is available, offer this hidden-input pattern:

```sh
printf 'OpenRouter API key: ' >&2
IFS= read -rs OPENROUTER_API_KEY
printf '\n' >&2
export OPENROUTER_API_KEY
```

The environment value belongs to that shell session. Launch Claude Code or Codex from the same shell, and use `unset OPENROUTER_API_KEY` when finished.

- Treat management credentials as separate. Request `OPENROUTER_MANAGEMENT_API_KEY` only for an explicit API-key administration task; never use it for inference or substitute it for `OPENROUTER_API_KEY`.
- Configure a management key with the matching host-specific hidden-input pattern above. Never request both keys unless the task genuinely needs both.

## Confirm spending in the conversation

- Run public or authenticated read-only lookups without extra confirmation.
- Treat every operation that can consume credits or incur a charge as spend-gated. This includes text inference, quick test messages, experiments and evals, image, audio, video, embeddings, reranking, paid tools, batches, and every retry that can be billed. If zero cost cannot be established from current official data, treat the operation as spend-gated.
- If the user's current prompt explicitly authorizes the specific spend-gated operation, execute it without asking again. Explicit authorization must clearly say to execute or proceed and acknowledge credit use, a charge, or a stated budget; a task description or general permission alone is not enough.
- Otherwise, state the model or endpoint, request summary, request count, and the known estimated cost or maximum budget in ordinary conversational text, then ask whether to proceed. Do not use an interactive confirmation card, `request_user_input`, `AskUserQuestion`, or a session-wide approval option.
- A clear affirmative reply authorizes the operation just described. Execute it without another confirmation. Ask again before a material change, additional request, or billable retry unless the user's approval explicitly covered it.
- Fail closed. If the user does not answer clearly, do not execute the call. Never infer approval from silence, an unrelated reply, or earlier general permission.
- `send-feedback`, credit purchases or transfers, account changes, API-key creation, rotation, update, disablement, or deletion, and workspace, member, budget, guardrail, privacy, BYOK, observability, or preset writes always require separate confirmation of the exact side effect. A missing or ambiguous response is a denial.
- Do not expose balances, key material, full key hashes, OAuth tokens, or sensitive stored generation content beyond what the user explicitly asks to inspect.
- Honor `Retry-After` for rate limits and availability errors. Do not retry a billable request without confirmation unless the user's approval explicitly covered retries.

## Select the official capability

- Live model discovery, pricing, endpoints, providers, benchmarks, rankings, credits, docs, quick test inference, images, generations, feedback, or Ori: use OpenRouter MCP first.
- Model discovery or comparison: use `openrouter-models` and `openrouter-benchmarks` when their richer workflow is needed.
- Reproducible prompt, parameter, or model experiments: use `run-openrouter-experiment`; use `spawn-ori-eval` for complete agent or coding harness evaluations.
- Dashboard-style administration, including assigned-key limits, API keys, credits, organizations, workspaces, members, budgets, guardrails, BYOK, observability, privacy controls, or presets: use `openrouter-key-management`. Prefer current official APIs; use the exact official page only when no public endpoint exists. A regular inference key is enough to inspect its own limits; management writes require a separate management key and confirmation.
- TypeScript agent or SDK work: use `openrouter-typescript-sdk`, `openrouter-agent-migration`, `create-agent-tui`, or `create-headless-agent` as applicable.
- Images, speech-to-text, text-to-speech, or video: use the matching `openrouter-images`, `openrouter-stt`, `openrouter-tts`, or `openrouter-video` skill.
- Analytics or generation inspection: use `openrouter-analytics`, its schema/query skills, or `openrouter-generations`.
- Application OAuth: use `openrouter-oauth`. Do not confuse application OAuth with MCP connection OAuth.
- Capabilities without a bundled skill, including Responses, Batch, embeddings, rerank, or another newly released endpoint: search current official docs and use the official REST API or SDK directly.
- Plugin refreshes or official skill snapshot checks: use `update-openrouter-plugin`. Apply only its allowlisted safe changes automatically.

Use the official snapshot provenance in the plugin root `OFFICIAL_SOURCES.md` only when auditing or updating the integration.