OmniRoute Provider Plugin for OpenClaw
Registers OmniRoute — a multi-provider model routing proxy — as a first-class text inference, embedding, image generation, video generation, music generation, speech, batch audio transcription, web fetch, and web search provider in OpenClaw. Install the plugin from ClawHub. Routes through models from 236+ providers with automatic fallback, live model discovery, and OpenAI-compatible transport.
Current release: 2.5.0. See the changelog for version history
and the GitHub Release
for the compatibility contract and verification record.
The supported OpenClaw floor remains 2026.7.1. On hosts that expose the async
SDK APIs, provider readiness and standalone catalog auditing use awaited auth
checks and cold config preparation. Older hosts use their existing synchronous
APIs; a failed async operation is never retried through the older path.
Quick Start
# Install from ClawHub
openclaw plugins install clawhub:@ekinnee/omniroute-provider
# If OmniRoute runs remotely, point the plugin at its reachable `/v1` endpoint.
# Skip this when OmniRoute runs on the same host at the default address.
openclaw config set models.providers.omniroute \
'{"api":"openai-completions","baseUrl":"https://omniroute.example.com/v1","models":[]}' \
--strict-json
# Set your OmniRoute API key
export OMNIROUTE_API_KEY="your-key-here"
# Verify it works
openclaw models list | grep omniroute
OmniRoute appears as a model provider after authenticated discovery. The gateway URL is models.providers.omniroute.baseUrl; its default, http://localhost:20128/v1, works only when OmniRoute runs on the same host. For discovery, chat, embeddings, image, video and music generation, speech, batch transcription, web fetch, web search, usage, and the catalog audit, an explicit non-default provider URL wins; otherwise OMNIROUTE_BASE_URL is used before the localhost default. Select any chat-capable model or combo returned by your OmniRoute gateway; the available list depends on that gateway's configured upstream providers and API-key permissions.
For an explicit provider-discovery refresh on current OpenClaw hosts, run
openclaw models list --refresh. OmniRoute's authenticated listing remains the
source of model availability; OpenClaw's hosted catalog does not replace it.
Text models advertised with supported_endpoints: ["responses"] are included
because OmniRoute translates their requests through /v1/chat/completions.
Their advertised limits and capabilities are preserved just like other chat rows.
Failed chat discovery reports unavailable to hosts that support discovery
outcomes, allowing OpenClaw to retain the same credential's last good list and
retry. Older supported hosts still receive an empty provider projection without
a thrown catalog-hook error. A valid empty listing or missing credential remains
a no-result response; the plugin does not invent fallback models.
When OmniRoute returns HTTP 401 with the structured code provider_not_configured,
the selected route fails as a request/configuration error without cooling down
the shared OmniRoute credential. Connect the upstream account or select an
available route. Other authentication and permission errors keep OpenClaw's
normal handling; the plugin does not exempt generic 401 or 403 responses.
This behavior is verified on OpenClaw 2026.10.10 and newer tested hosts. The
supported 2026.7.1 package has an existing error-hook loading limitation, so
install compatibility with that floor does not provide this classification fix.
Upgrading to 2.0.0
Version 2 removes the plugin's synthetic omniroute/auto catalog entry and automatic default-model selection. Existing provider configuration is preserved, but it is not rewritten to choose a replacement model.
After upgrading, authenticate to OmniRoute and run openclaw models list to refresh the live catalog. Select an advertised omniroute/<model-id> or omniroute/<combo-id> for each primary, fallback, or manually configured omniroute/auto reference. You can keep omniroute/auto only when your authenticated OmniRoute gateway actually returns auto; different users can receive different catalogs. Fresh onboarding configures the provider and authentication only, without selecting a model.
Configuration
Environment
| Variable | Required | Default | Description |
|---|---|---|---|
OMNIROUTE_API_KEY | Yes | — | API key for your OmniRoute gateway |
OMNIROUTE_BASE_URL | No | http://localhost:20128/v1 | Custom base URL |
OpenClaw Config
Set the OmniRoute gateway URL in your OpenClaw config. Include the /v1 path; this is the canonical setting for every plugin capability.
{
models: {
providers: {
omniroute: {
api: "openai-completions",
baseUrl: "https://omniroute.example.com/v1",
models: [],
},
},
},
}
The empty models array is intentional: OpenClaw requires it for an authored custom provider, and the plugin supplies the authenticated live models during discovery. For a LAN-hosted gateway, substitute its reachable host and port. models.providers.omniroute.baseUrl is the durable configuration option; OMNIROUTE_BASE_URL is the fallback when that setting is absent or still the public localhost default.
Transport TLS limitation
For plugin-owned discovery, catalog audit, embeddings, image/video/music generation, speech, batch transcription, and search requests, target TLS overrides in models.providers.omniroute.request.tls cannot be combined with request.proxy.mode: "explicit-proxy". The plugin rejects this combination before making the request because the guarded SDK transport cannot represent independent target TLS settings for an explicit proxy. Direct and env-proxy transport retain support for target TLS overrides. This does not change the compatibility floor or OpenClaw-owned chat transport.
Catalog Metadata Audit
The plugin package includes a read-only catalog audit command. It loads the same OpenClaw configuration and agent-scoped OmniRoute credentials, performs GET /v1/models, and reports only metadata the gateway actually advertised.
# When the package executable is linked into PATH
omniroute-catalog-audit --agent main
# JSON output from a default ClawHub extension install
node "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/extensions/omniroute/dist/catalog-audit-bin.js" \
--agent main --json
The report classifies chat, embedding, image, and other rows; identifies invalid rows, duplicate IDs, and relevant missing advertised metadata; and redacts credentials and URL query strings. Missing metadata stays unknown—it is not replaced with a guessed model capability. The command makes no configuration changes and sends no inference request.
Embeddings
OmniRoute can also serve OpenClaw embedding requests through POST /v1/embeddings.
Configure a specific embedding model from OmniRoute's GET /v1/models response:
{
agents: {
defaults: {
memorySearch: {
provider: "omniroute",
model: "provider/embedding-model-from-omniroute",
},
},
},
}
The plugin does not default embeddings to auto. Embedding model and dimensionality are part of the vector index identity, so changing either can invalidate an existing index or make queries fail.
Image Generation
OmniRoute can serve OpenClaw image generation requests through POST /v1/images/generations and image edits through POST /v1/images/edits.
Configure a specific image model from OmniRoute's GET /v1/models response:
{
agents: {
defaults: {
imageGenerationModel: {
primary: "omniroute/provider/image-model-from-omniroute",
},
},
},
}
Image editing requires OmniRoute v3.8.11 or newer. For an edit, supply exactly one reference image and select an OmniRoute model that supports image editing. The plugin sends the reference image as a data URL in a JSON request to /v1/images/edits. Masks and multiple reference images are not currently supported.
The plugin does not default image generation or editing to auto; use a model that OmniRoute advertises for the requested operation.
Video Generation
When OmniRoute returns both inline b64_json video data and a URL, the plugin
prefers the decoded inline bytes and returns a buffered asset. If inline data is
absent or decodes to no bytes, an available URL keeps its existing behavior.
URL-only results are still forwarded to OpenClaw; guarded materialization and
cleanup remain tracked in #50.
Web Search
OmniRoute can serve OpenClaw web search requests through POST /v1/search.
The plugin registers itself as a web search provider automatically — no additional configuration needed.
{
tools: {
web: {
search: {
provider: "omniroute",
maxResults: 10,
},
},
},
}
The web search tool supports query, count (1-10), freshness (day/week/month/year), country, and language parameters. Results include titles, URLs, snippets, and publication dates when OmniRoute supplies them.
Set tools.web.search.maxResults to choose the default result count (1-10).
When a call omits count, the plugin uses this setting, or 5 if it is unset.
An explicit count keeps its existing handling and takes precedence. The tool's
parameter description shows the effective default.
Web Fetch
OmniRoute can serve OpenClaw web fetch requests through POST /v1/web/fetch.
The plugin registers itself as a web-fetch provider automatically and uses the
shared OmniRoute credential and base URL configuration.
{
tools: {
web: {
fetch: {
provider: "omniroute",
},
},
},
}
OpenClaw supplies the target url, extractMode (markdown or text), and
host-owned maxChars limit. The plugin requests OmniRoute markdown, projects
plain text with OpenClaw's public helper when requested, preserves the final
URL, title, extractor, and upstream truncation signal, and leaves final content
length enforcement to OpenClaw. Private, loopback, and other special-use target
hostnames are rejected before forwarding. OmniRoute's provider-selection,
depth, selector-wait, link-list, metadata-description, and screenshot options
are not exposed because they are outside the OpenClaw 2026.7.1 web-fetch
contract.
Text to Speech
OmniRoute can serve OpenClaw speech synthesis requests through POST /v1/audio/speech.
Configure a model advertised by your OmniRoute gateway in the speech provider config;
the API key and shared gateway URL continue to come from the normal OmniRoute provider
configuration or environment variables:
{
messages: {
tts: {
provider: "omniroute",
providers: {
omniroute: {
model: "provider/tts-model-from-omniroute",
voice: "coral",
responseFormat: "mp3",
},
},
},
},
}
Supported voices are the OpenAI-compatible voice IDs exposed by the plugin. Supported
formats are mp3, opus, and wav; voice notes default to opus, while audio files
default to mp3. The plugin rejects missing models, unsupported voices, unsupported
formats, and responses whose MIME type or bytes do not match the requested format.
Batch Audio Transcription
OmniRoute can serve OpenClaw media-understanding audio transcription requests through
POST /v1/audio/transcriptions. Configure an explicitly selected transcription model
advertised by your OmniRoute gateway; the plugin does not invent an auto or fallback
model. This integration is batch REST transcription only. Realtime or duplex voice
transcription is not supported by this contract.
How It Works
- Authenticated live model discovery — The plugin fetches
GET /v1/modelsfrom your OmniRoute gateway and registers its chat-capable rows asomniroute/<model-id>. That response is authoritative: model and combo IDs are preserved exactly, and the available list varies with the gateway's upstream-provider configuration and the authenticated API key. - Authenticated media catalogs — The same credential-scoped response publishes image, video, and music rows through OpenClaw's modality-specific pickers. Model IDs and advertised capability objects are preserved; classification uses explicit type, endpoint, and output-modality metadata. Audio/voice catalog rows remain deferred, while speech synthesis and batch transcription use explicitly configured models through OpenClaw's speech and media-understanding contracts.
- No synthetic default — The plugin does not hardcode
auto, any other combo, or a fallback model. A model is shown only when OmniRoute advertises it; discovery failure does not fabricate a model selection. Chat rows missing a positive context or output limit are excluded from discovery until OmniRoute advertises both; the catalog audit still shows those rows and their missing metadata. - Catalog diagnostics — The packaged
omniroute-catalog-auditcommand shows the authenticated gateway's advertised metadata without filling gaps with plugin guesses. Discovery excludes rows with missing or invalid sizing; missing thinking tiers do not create controls. - Reasoning controls from metadata — A thinking selector is exposed only when the returned row advertises explicit
effort_tiers.supportsThinkingwithout those tiers still marks the model as reasoning-capable, but it does not inventnone/low/medium/high/xhighcontrols. OpenClaw's off state is sent asreasoning_effort: "none"; supported non-off levels are passed through using the returned effort metadata. OpenClaw continues to own the configured/session default when no level is explicitly selected—the plugin does not invent another default. - OpenAI-compatible transport — Text requests use standard OpenAI chat completions format (
POST /v1/chat/completions) with streaming usage support. - Configured embeddings — Embedding requests use OmniRoute's OpenAI-compatible
POST /v1/embeddingsendpoint and require a configured embedding model. - Configured image generation and editing — Image generation uses
POST /v1/images/generations. Edits send one reference image as a JSON data URL toPOST /v1/images/edits. Both require a configured OmniRoute model that supports the requested operation. - Music generation — Music requests use
POST /v1/music/generationswith an explicitly selected model and prompt. Inline base64 and hosted URL results are materialized as bounded audio assets through guarded transport; edit and image-conditioned modes remain disabled until OmniRoute exposes a uniform contract. - Speech synthesis — Speech requests use OmniRoute's
POST /v1/audio/speechendpoint with an explicitly configured model, supported voice, and output format. - Batch audio transcription — Audio requests use OmniRoute's multipart
POST /v1/audio/transcriptionsendpoint with an explicitly configured model. OpenClaw's public multipart helper preserves the upload filename and MIME type, while bounded response validation rejects missing transcript text. - Web search — Search requests use OmniRoute's
POST /v1/searchendpoint. The plugin registers as a web search provider automatically. - Web fetch — Fetch requests use OmniRoute's
POST /v1/web/fetchendpoint with markdown extraction and metadata enabled. The adapter preserves the public OpenClaw result fields and does not implement a second provider fallback policy. - Provider quota usage — OpenClaw status and usage views can read OmniRoute's credential-scoped cached quota snapshot from
GET /api/usage/om-usage?format=json. Enable usage visibility for that OmniRoute API key; a key without that permission reports an explicit unavailable status and never exposes other gateway connections.
Usage windows use raw consumption from the gateway-selected connection, without
combining other connections or applying quota cutoffs. Valid quota labels and
reset times are preserved; malformed or unlimited windows are omitted, and
over-quota percentages are capped at 100 for display. Older gateways returning
recognizable legacy text still work through the existing bounded parser. That
text reports cutoff-adjusted allowance, so percentages can differ: 60% raw usage
with a 25% cutoff is 60% used in JSON, while legacy 20% left is 80% used.
Malformed JSON, structured refusals and HTTP failures do not trigger text fallback
or a second request.
Temperature suppression and arbitrary provider-specific request flags are not inferred from catalog rows. They require future transport-level support and validation.
Roadmap
The plugin currently exposes OmniRoute as OpenAI-compatible chat, embedding, image-generation, video-generation, music-generation, speech, batch audio transcription, web-fetch, and web-search providers. The longer-term goal is to cover OmniRoute's full published API surface as OpenClaw plugin capabilities mature.
Implementable in Plugin (OpenClaw SDK surface exists)
| Capability | Status |
|---|---|
Chat completions (/v1/chat/completions) | ✅ Initial support |
Live model catalog (GET /v1/models) | ✅ Initial support |
Modality-specific model catalogs (GET /v1/models) | ✅ Initial support — publish authenticated image, video, and music rows; audio/voice catalog rows remain deferred |
Embeddings (/v1/embeddings) | ✅ Initial support |
Async embedding batches (/v1/files + /v1/batches) | ⏳ OpenClaw contract merged in #129625; implement after it ships in a stable release (tracking issue #58) |
Image generation (/v1/images/generations) | ✅ Initial support |
Image edits (/v1/images/edits) | ✅ Supported with OmniRoute v3.8.11+ — one reference image with an edit-capable model; no masks or multiple references |
Web search (/v1/search) | ✅ Initial support |
Speech (/v1/audio/speech) | ✅ Initial support — explicit model, supported voice, and bounded standard output formats |
Batch transcription (/v1/audio/transcriptions) | ✅ Initial support — explicit model, multipart upload, and bounded transcript validation; not realtime transcription |
Web fetch (/v1/web/fetch) | ✅ Initial support — maps the public URL, extract mode, max-character, title, final-URL, extractor, and truncation fields; richer OmniRoute fetch options remain deferred |
Video generation (/v1/videos/generations) | ✅ Initial support |
Music generation (/v1/music/generations) | ✅ Initial support — prompt generation with inline or hosted audio; edits deferred |
Needs a broader OpenClaw SDK surface
| OmniRoute Endpoint | Notes |
|---|---|
/v1/responses | OpenAI Responses API — no OpenClaw provider surface |
/v1/completions | Legacy completions — no OpenClaw provider surface |
/v1/messages | Anthropic-compatible — no OpenClaw provider surface |
/v1/rerank | Cohere-compatible rerank — no OpenClaw provider surface |
/v1/moderations | OpenAI-compatible moderation — no OpenClaw provider surface |
/v1/batches, /v1/files | OpenClaw main now exposes an embedding-specific asynchronous batch runtime. Generic file and non-embedding batch operations still have no plugin surface. |
Development
git clone https://github.com/ekinnee/omniroute-openclaw
cd omniroute-openclaw
pnpm install
pnpm test
License
MIT
