mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-05-22 19:57:07 +00:00

Diego Rodrigues de Sa e Souza 91b6983564

Release v3.8.1 — feature flags settings page, bracketed combo names, security hardening, multi-driver SQLite

2026-05-21 01:29:12 -03:00

7.4 KiB

Raw Permalink Blame History

title	version	lastUpdated
OpenCode Integration	3.8.1	2026-05-14

OpenCode Integration

Status: Generally available. Audience: Operators wiring OpenCode to an OmniRoute deployment. Source of truth (config schema): src/shared/services/opencodeConfig.ts Source of truth (npm package): @omniroute/opencode-provider/ (publishable workspace)

OpenCode is an agentic CLI/desktop AI client. It reads its provider catalog from ~/.config/opencode/opencode.json (or opencode.jsonc) and follows the schema at https://opencode.ai/config.json. OmniRoute exposes itself to OpenCode as one of those providers — every request flows through OmniRoute's standard OpenAI-compatible /v1 surface, so OpenCode automatically benefits from Auto-Combo routing, circuit breakers, key policies, observability, etc.

There are two supported integration paths. Pick one — they generate the same config.

Path 1 — CLI generator (no npm install)

Recommended for end users. Ships with OmniRoute. Writes opencode.json in place.

# After installing OmniRoute (npm i -g @omniroute/cli or local clone)
omniroute config opencode \
  --baseUrl http://localhost:20128 \
  --apiKey "$OMNIROUTE_API_KEY"

Behind the scenes the CLI calls mergeOpenCodeConfigText() (src/shared/services/opencodeConfig.ts:104), so an existing opencode.json keeps its other providers and comments. The OmniRoute entry is added/replaced atomically.

Resulting file (default model catalog):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1",
        "apiKey": "<your-key>",
      },
      "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" },
      },
    },
  },
}

Path 2 — npm package `@omniroute/opencode-provider`

Recommended when you're scripting the config from Node/TS (CI pipelines, monorepos, custom installer flows).

npm install --save-dev @omniroute/opencode-provider

import { writeFileSync } from "node:fs";
import { buildOmniRouteOpenCodeConfig } from "@omniroute/opencode-provider";

const config = buildOmniRouteOpenCodeConfig({
  baseURL: "http://localhost:20128",
  apiKey: process.env.OMNIROUTE_API_KEY ?? "sk_omniroute",
  // Optional: override the model catalog exposed to OpenCode
  models: ["auto", "claude-opus-4-7", "gpt-5.5"],
  modelLabels: { auto: "Auto-Combo" },
});

writeFileSync("opencode.json", JSON.stringify(config, null, 2));

For a non-destructive merge against an existing file, replicate mergeOpenCodeConfigText() from opencodeConfig.ts or call the CLI generator.

See the package README for the full API.

What the runtime actually does

Both paths produce the same provider.omniroute.npm: "@ai-sdk/openai-compatible". At runtime, OpenCode loads @ai-sdk/openai-compatible (already a transitive dependency of OpenCode) and configures it with baseURL + apiKey. From there:

OpenCode UI/agent
   → @ai-sdk/openai-compatible
      → HTTP POST {baseURL}/chat/completions          (OmniRoute OpenAI surface)
         → OmniRoute /v1/chat/completions handler     (open-sse/handlers/chatCore.ts)
            → combo routing / Auto-Combo / executor
               → upstream provider

The plugin never touches HTTP. It only emits configuration.

Model catalog defaults

export const OMNIROUTE_DEFAULT_OPENCODE_MODELS = [
  "claude-opus-4-5-thinking",
  "claude-sonnet-4-5-thinking",
  "gemini-3.1-pro-high",
  "gemini-3-flash",
] as const;

You can override via models: [...]. Recommended additions:

"auto" — surfaces OmniRoute's Auto-Combo zero-config router. Lets OpenCode pick "the best available model" without you hard-coding the catalog.
"<combo-name>" — any combo you've defined in the dashboard; OmniRoute resolves it transparently.

URL normalisation

The helper accepts both forms and emits exactly one /v1:

Input	Output (`options.baseURL`)
`http://localhost:20128`	`http://localhost:20128/v1`
`http://localhost:20128/`	`http://localhost:20128/v1`
`http://localhost:20128/v1`	`http://localhost:20128/v1`
`http://localhost:20128/v1///`	`http://localhost:20128/v1`

This deduplication is the most common breakage seen in older configs. If you have an opencode.json from before v3.8.0 that points at /v1/v1/..., re-run the generator or call createOmniRouteProvider again.

Authentication modes

OmniRoute setting	Recommended `apiKey` value
`REQUIRE_API_KEY=false` (default for local)	`sk_omniroute` (literal placeholder)
`REQUIRE_API_KEY=true`	A real per-user API key from Dashboard → API Manager.

For Anthropic-style clients that send x-api-key + anthropic-version, OmniRoute's extractApiKey also honours the key from x-api-key. OpenCode uses the OpenAI surface, so it'll always send Authorization: Bearer ${apiKey} — no Anthropic special-case applies here.

Troubleshooting

Symptom	Cause	Fix
`404` on every request with URL containing `/v1/v1/`	Stale config from pre-v3.8 plugin that double-suffixed `/v1`.	Regenerate via Path 1 or 2.
`401 Invalid API key`	OmniRoute has `REQUIRE_API_KEY=true` and the key is unknown.	Create the key in the dashboard, or set `REQUIRE_API_KEY=false` (local only) and use `sk_omniroute`.
Model list empty in OpenCode UI	All 4 default models are hidden in OmniRoute's provider visibility.	Pass `models: ["auto", ...]` to surface ones you've enabled.
OpenCode 500 with `cannot read property 'models'`	Older OpenCode (< 0.1.x) didn't accept inline `models`.	Upgrade OpenCode to a version that follows the v1 schema (`opencode.ai/config.json`).

7.4 KiB Raw Permalink Blame History