Spaces:
Runtime error
Runtime error
| # @omniroute/opencode-provider | |
| > ## ⚠️ Deprecated — use [`@omniroute/opencode-plugin`](https://www.npmjs.com/package/@omniroute/opencode-plugin) instead | |
| > | |
| > This package writes a **static** `provider.omniroute` block to `opencode.json` from a hardcoded default model list, so it **drifts behind your live OmniRoute catalog** — adding a model in OmniRoute won't show up in OpenCode until you re-run the generator, and OpenCode Desktop/Web only surfaces a subset of the static models. | |
| > | |
| > **`@omniroute/opencode-plugin`** solves this by fetching `GET /v1/models` from your OmniRoute instance at OpenCode startup, so the model list is always live (see [#3419](https://github.com/diegosouzapw/OmniRoute/issues/3419)). It is now the recommended path. | |
| > | |
| > **One-line migration** — replace the static `provider.omniroute` block in `opencode.json` with a single plugin entry: | |
| > | |
| > ```jsonc | |
| > // opencode.json | |
| > { | |
| > "$schema": "https://opencode.ai/config.json", | |
| > "plugin": ["@omniroute/opencode-plugin"] | |
| > } | |
| > ``` | |
| > | |
| > This package is **not removed** and still works for static/offline config generation, but it is no longer actively recommended and won't track new models automatically. | |
| Helper for connecting [OpenCode](https://opencode.ai) to a running [OmniRoute](https://github.com/diegosouzapw/OmniRoute) AI gateway. | |
| The package emits a **schema-valid entry** for `opencode.json` (`https://opencode.ai/config.json`) that delegates the actual runtime to [`@ai-sdk/openai-compatible`](https://www.npmjs.com/package/@ai-sdk/openai-compatible). It does not ship any new HTTP client — OmniRoute already exposes an OpenAI-compatible surface, and OpenCode already speaks it through the AI SDK. | |
| > Pre-1.0. The API may still change. See `CHANGELOG` in the OmniRoute repo for breaking notes. | |
| ## Installation | |
| ```bash | |
| npm install --save-dev @omniroute/opencode-provider | |
| # or | |
| pnpm add -D @omniroute/opencode-provider | |
| ``` | |
| You also need OpenCode's own runtime dep, but that's a transitive concern — OpenCode itself ships with `@ai-sdk/openai-compatible`. This package only **generates configuration**. | |
| ## Quick start | |
| ### 1. Scaffold a fresh `opencode.json` | |
| ```ts | |
| import { writeFileSync } from "node:fs"; | |
| import { buildOmniRouteOpenCodeConfig } from "@omniroute/opencode-provider"; | |
| const config = buildOmniRouteOpenCodeConfig({ | |
| baseURL: "http://localhost:20128", // or your OmniRoute deployment URL | |
| apiKey: process.env.OMNIROUTE_API_KEY ?? "sk_omniroute", | |
| }); | |
| writeFileSync("opencode.json", JSON.stringify(config, null, 2)); | |
| ``` | |
| The resulting `opencode.json`: | |
| ```jsonc | |
| { | |
| "$schema": "https://opencode.ai/config.json", | |
| "provider": { | |
| "omniroute": { | |
| "npm": "@ai-sdk/openai-compatible", | |
| "name": "OmniRoute", | |
| "options": { | |
| "baseURL": "http://localhost:20128/v1", | |
| "apiKey": "sk_omniroute", | |
| }, | |
| "models": { | |
| "claude-opus-4-5-thinking": { "name": "claude-opus-4-5-thinking" }, | |
| "claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" }, | |
| "gemini-3.1-pro-high": { "name": "gemini-3.1-pro-high" }, | |
| "gemini-3-flash": { "name": "gemini-3-flash" }, | |
| }, | |
| }, | |
| }, | |
| } | |
| ``` | |
| ### 2. Merge into an existing `opencode.json` | |
| ```ts | |
| import { createOmniRouteProvider } from "@omniroute/opencode-provider"; | |
| const provider = createOmniRouteProvider({ | |
| baseURL: "http://localhost:20128", | |
| apiKey: process.env.OMNIROUTE_API_KEY!, | |
| }); | |
| // Place `provider` under provider.omniroute in your opencode.json | |
| ``` | |
| If you already have an `opencode.json` on disk and want a non-destructive merge from the OmniRoute side, use `omniroute config opencode` from the CLI (ships with the main OmniRoute install) — it preserves comments and unrelated keys. | |
| ## API | |
| ### `createOmniRouteProvider(options): OpenCodeProviderEntry` | |
| Returns the value to place under `provider.omniroute` inside `opencode.json`. | |
| | Option | Type | Required | Description | | |
| | ------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | |
| | `baseURL` | `string` | Yes | OmniRoute base URL. Accepts `http://host:port` **or** `http://host:port/v1`. Trailing slashes are tolerated. | | |
| | `apiKey` | `string` | Yes | OmniRoute API key. Use `sk_omniroute` for local installs that have `REQUIRE_API_KEY=false`. | | |
| | `displayName` | `string` | No | Custom name shown in the OpenCode UI. Default: `"OmniRoute"`. | | |
| | `models` | `string[]` | No | Override the surfaced model catalog. Default: 4 curated models — see `OMNIROUTE_DEFAULT_OPENCODE_MODELS`. | | |
| | `modelLabels` | `Record<string,string>` | No | Human-readable labels keyed by model id. | | |
| Throws on empty/invalid input — `baseURL` must be a real URL, `apiKey` must be a non-empty string. | |
| ### `buildOmniRouteOpenCodeConfig(options): OpenCodeConfigDocument` | |
| Same options as above, but returns a full document with `$schema` and the `provider.omniroute` wrapper, ready to write to `opencode.json`. | |
| ### `normalizeBaseURL(input): string` | |
| Exported for completeness. Strips trailing `/`, deduplicates a trailing `/v1`, and re-appends exactly one `/v1`. Throws on empty / non-URL input. | |
| ### Constants | |
| - `OMNIROUTE_PROVIDER_KEY` — `"omniroute"` (the key used under `provider.*`). | |
| - `OMNIROUTE_PROVIDER_NPM` — `"@ai-sdk/openai-compatible"` (the runtime delegate). | |
| - `OPENCODE_CONFIG_SCHEMA` — `"https://opencode.ai/config.json"`. | |
| - `OMNIROUTE_DEFAULT_OPENCODE_MODELS` — readonly list of default model ids. | |
| ## Custom model catalog | |
| ```ts | |
| import { createOmniRouteProvider } from "@omniroute/opencode-provider"; | |
| createOmniRouteProvider({ | |
| baseURL: "http://localhost:20128", | |
| apiKey: "sk_omniroute", | |
| models: ["auto", "claude-opus-4-8", "gpt-5.5"], | |
| modelLabels: { | |
| auto: "Auto-Combo (recommended)", | |
| "claude-opus-4-8": "Claude Opus 4.8", | |
| "gpt-5.5": "GPT-5.5", | |
| }, | |
| }); | |
| ``` | |
| Duplicates and empty strings are dropped automatically, and order is preserved. | |
| ## Troubleshooting | |
| - **Requests 404 with `/v1/v1/...`** — you're on an old version (≤1.0.0). Update to `≥0.1.0` of this re-released package. The new build normalises `baseURL` automatically. | |
| - **`401 Invalid API key`** — your OmniRoute instance has `REQUIRE_API_KEY=true` but the key you supplied doesn't exist there. Create one via the dashboard or set `REQUIRE_API_KEY=false` and use `sk_omniroute`. | |
| - **OpenCode complains the provider has no models** — supply an explicit `models` list; the default 4 may be hidden by your provider visibility settings. | |
| ## Related | |
| - [OmniRoute](https://github.com/diegosouzapw/OmniRoute) — the AI gateway this plugin targets. | |
| - [OpenCode](https://opencode.ai) — the agentic CLI consumer. | |
| - [`@ai-sdk/openai-compatible`](https://www.npmjs.com/package/@ai-sdk/openai-compatible) — the runtime delegate that actually speaks HTTP. | |
| ## License | |
| MIT — see [`LICENSE`](./LICENSE). | |