This documentation set covers installation, configuration, operations, and security for the Open WebUI pipe that targets the OpenRouter Responses API.
Use these docs if you want to install the pipe, select OpenRouter models in Open WebUI, and troubleshoot common errors.
Use these docs if you run Open WebUI for multiple users and need secure configuration, deployment guidance, operational controls, and incident-ready logging.
Use these docs if you are modifying the pipe, working on tests, or extending the integrations.
- Open WebUI
0.8.0or later (the pipe declares this requirement in its manifest header). - An OpenRouter API key, provided either via the
OPENROUTER_API_KEYenvironment variable or via the pipe’s valve configuration.
-
In Open WebUI, go to Admin → Functions → New Function.
-
Import one of the bundled pipe files and paste a URL:
Readable bundle (audits or troubleshooting):
https://github.com/rbb-dev/Open-WebUI-OpenRouter-pipe/releases/latest/download/open_webui_openrouter_pipe_bundled.pyCompressed bundle (routine installs; smaller payload, faster upload, same runtime behavior):
https://github.com/rbb-dev/Open-WebUI-OpenRouter-pipe/releases/latest/download/open_webui_openrouter_pipe_bundled_compressed.py -
Save and enable the function.
Open WebUI installs the Python dependencies declared in the function header (requirements:). This pipe declares (at least) aiohttp, cryptography, fastapi, httpx, lz4, pydantic, pydantic_core, sqlalchemy, tenacity, and pyzipper, plus cairosvg and Pillow (used to import OpenRouter model icons into Open WebUI as PNG data URLs).
- Open WebUI Valves are the configuration surface for this pipe. At minimum, configure the OpenRouter API key (or set
OPENROUTER_API_KEYin the Open WebUI environment). - For the authoritative list of valves (including verified defaults), see: Valves & Configuration Atlas.
After enabling the function, Open WebUI will expose OpenRouter models (imported from OpenRouter’s model catalog) in the model selector. Choose a model and chat normally.
This pipe can automatically sync Open WebUI model metadata for the OpenRouter models it exposes:
UPDATE_MODEL_IMAGEScontrols whether model profile images are downloaded and stored in Open WebUI.UPDATE_MODEL_DESCRIPTIONScontrols whether model descriptions are synced from the OpenRouter catalog.UPDATE_MODEL_CAPABILITIEScontrols whether model capability checkboxes are synced.
See: OpenRouter Integrations & Telemetry.
This pipe supports OpenRouter model variants (:nitro, :free, :exacto, etc.) and user-defined presets. Configure VARIANT_MODELS to expose these as separate model selector entries.
See: Model Variants & Presets.
- Confirm the function is enabled in Admin → Functions.
- Confirm the pipe is configured with a valid API key (valve or
OPENROUTER_API_KEYenvironment variable). - If your deployment blocks outbound internet access, ensure it can reach the OpenRouter API endpoint configured by
BASE_URL.- The model list is populated by refreshing the OpenRouter catalog; when the refresh fails and no cached catalog exists, Open WebUI will show no models until connectivity and credentials are fixed.
- Validate the configured key and confirm it is being provided where you expect (valves vs environment variables).
- If you run Open WebUI behind a proxy/gateway, verify
BASE_URLpoints to your gateway and that the gateway is correctly forwarding auth headers.
- Remote downloads are subject to SSRF filtering and size limits, with HTTPS-only defaults (HTTP allowlist available). Review your remote download settings in Valves & Configuration Atlas and the deep-dive in Multimodal Ingestion Pipeline.
- Review concurrency limits, queueing behavior, and breaker controls in Concurrency Controls & Resilience.
- See Error Handling & User Experience for operator-facing troubleshooting and error template behavior.
- Valves & Configuration Atlas — authoritative configuration reference (defaults verified against code/tests).
- Error Handling & User Experience — what users see, how errors are structured, and how to troubleshoot.
- OpenRouter Direct Uploads (bypass OWUI RAG) — forward chat uploads to OpenRouter as direct files/audio/video with per-chat toggles and safety gates.
- OpenRouter Provider Routing — control which infrastructure providers serve your requests with per-model filters, ORDER dropdowns, and compliance options (ZDR, fallbacks).
- OpenRouter Integrations & Telemetry — identifiers, metadata, optional telemetry exports, and OpenRouter-facing headers.
- Web Search (Open WebUI) vs OpenRouter Search — explains the two web-search toggles and how OpenRouter Search is auto-installed, only shown on models where it can work, and enabled by default (while still allowing per-model and per-chat control).
- Model Variants & Presets — create virtual model entries for OpenRouter variants (
:nitro,:exacto, etc.) and user-defined presets (@preset/your-preset) to expose specialized routing options in the model selector.
- Security & Encryption — key handling, SSRF controls (HTTPS-only by default), and hardening guidance.
- Zero Data Retention (ZDR) — ZDR model filtering and enforcement controls.
- Persistence, Encryption & Storage — what is persisted, how retention works, and operational considerations.
- Request Identifiers & Abuse Attribution — multi-user identifiers and privacy guidance.
- Session Log Storage — optional encrypted, per-request archives for incident response.
- Concurrency Controls & Resilience — admission control, breaker behavior, and tuning guidance.
- Streaming Pipeline & Emitters — streaming lifecycle, emitters, and User Interface/performance tradeoffs.
- Testing, Bootstrap & Operations — test harness, dev bootstrap, and operational runbooks.
- Production Readiness Report — an assessment-style document (treat as guidance, not a compliance guarantee).
- Developer Guide & Architecture
- Model Catalog & Routing Intelligence
- History Reconstruction & Context
- Multimodal Ingestion Pipeline
- Task Models & Housekeeping
- Tooling & Integrations
- Test Suite Audit Snapshot — one-shot snapshot of a completed test audit; not maintained.
CHANGELOG.md(repo root) — audit trail for changes.