mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-18 13:14:56 +03:00
docs: add the VS Code Copilot Chat guide and document the /v1/models prefix modes (#10648)
Adds docs/guides/VSCODE-COPILOT.md covering the OmniCopilot extension: install from either store, connection setup, what the picker actually shows and why, the dashboard-in-a-tab mode, and a troubleshooting table. Documents two contracts that existed in code but nowhere in the docs: - The ?prefix= query parameter on GET /v1/models, with the warning that "canonical" omits providers whose alias already is the canonical id — so "alias" is the safe direction for a de-duplicated list. - MODELS_CATALOG_PREFIX_MODE in .env.example and ENVIRONMENT.md, matching how ARENA_ELO_SYNC_ENABLED and PII_REDACTION_ENABLED are already documented. The fabricated-docs gate cannot see this flag being read, because resolveFeatureFlag() indexes process.env by key rather than naming it; added an allowlist entry explaining that, in the style of the existing entries. Co-authored-by: Xiangzhe <bakryun0718@proton.me>
This commit is contained in:
Diego Rodrigues de Sa e Souza
committed by
GitHub
GitHub
parent
c164ed962b
commit
8ba25e9318
10
.env.example
10
.env.example
@@ -1648,6 +1648,16 @@ APP_LOG_TO_FILE=true
|
||||
# Used by: src/shared/constants/featureFlagDefinitions.ts, src/lib/arenaEloSync.ts
|
||||
# ARENA_ELO_SYNC_ENABLED=true
|
||||
|
||||
# How model ids are prefixed in GET /v1/models. "dual" (default) advertises BOTH the
|
||||
# short alias prefix and the canonical provider prefix for each model (cc/claude-sonnet-4-6
|
||||
# AND claude/claude-sonnet-4-6) so client configs that hardcoded either form keep working —
|
||||
# which roughly doubles the catalog. "alias" emits one id per model; "canonical" emits only
|
||||
# the full provider-id prefix (and drops providers whose alias is already canonical).
|
||||
# A client can override per request with GET /v1/models?prefix=alias instead.
|
||||
# Also configurable from Dashboard > Settings > Feature Flags.
|
||||
# Used by: src/shared/constants/featureFlagDefinitions.ts, src/app/api/v1/models/catalog.ts
|
||||
# MODELS_CATALOG_PREFIX_MODE=dual
|
||||
|
||||
# Sync interval in seconds. Default: 86400 (24 hours).
|
||||
# ARENA_ELO_SYNC_INTERVAL=86400
|
||||
|
||||
|
||||
@@ -433,6 +433,7 @@ For any non-trivial change, read the matching deep-dive first:
|
||||
| Provider catalog (auto-generated) | `docs/reference/PROVIDER_REFERENCE.md` |
|
||||
| Tunnels | `docs/ops/TUNNELS_GUIDE.md` |
|
||||
| Electron desktop app | `docs/guides/ELECTRON_GUIDE.md` |
|
||||
| VS Code Copilot Chat (OmniCopilot extension) | `docs/guides/VSCODE-COPILOT.md` |
|
||||
| Release flow | `docs/ops/RELEASE_CHECKLIST.md` |
|
||||
| Embedded services | `docs/frameworks/EMBEDDED-SERVICES.md` |
|
||||
| Quality gates (~80 scripts, allowlist policy) | `docs/architecture/QUALITY_GATES.md` |
|
||||
|
||||
@@ -737,6 +737,8 @@ From inside the editor: open the **Extensions** view, search **"OmniRoute"**, cl
|
||||
— works the same way on both stores. Source, issues and the publishing runbook live at
|
||||
[diegosouzapw/OmniCopilot](https://github.com/diegosouzapw/OmniCopilot).
|
||||
|
||||
<sub>📖 [VS Code Copilot Chat guide](docs/guides/VSCODE-COPILOT.md) — setup, what the picker shows, dashboard-in-a-tab, troubleshooting</sub>
|
||||
|
||||
<br/>
|
||||
|
||||
<div align="center">
|
||||
|
||||
@@ -24,6 +24,8 @@ per-tool deep dives:
|
||||
- [Claude Code configuration](./CLAUDE-CODE-CONFIGURATION.md)
|
||||
- [Codex CLI configuration](./CODEX-CLI-CONFIGURATION.md)
|
||||
- [Remote Mode](./REMOTE-MODE.md) — drive a remote OmniRoute (VPS / Tailnet) from your laptop
|
||||
- [VS Code Copilot Chat](./VSCODE-COPILOT.md) — the OmniCopilot extension; it can also run these
|
||||
`setup-*` commands for you from inside the editor
|
||||
|
||||
---
|
||||
|
||||
|
||||
138
docs/guides/VSCODE-COPILOT.md
Normal file
138
docs/guides/VSCODE-COPILOT.md
Normal file
@@ -0,0 +1,138 @@
|
||||
---
|
||||
title: "VS Code Copilot Chat — OmniCopilot extension"
|
||||
version: 3.8.50
|
||||
lastUpdated: 2026-08-18
|
||||
---
|
||||
|
||||
# VS Code Copilot Chat — OmniCopilot extension
|
||||
|
||||
**OmniCopilot** puts every model your OmniRoute serves into the *native* GitHub Copilot Chat
|
||||
model picker. No second sidebar, no separate chat UI — Copilot's agent mode, tool calling,
|
||||
MCP servers and custom instructions all keep working, just running on the model you pick.
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| **Install (VS Code)** | [Marketplace → `diegosouzapw.omnicopilot`](https://marketplace.visualstudio.com/items?itemName=diegosouzapw.omnicopilot) |
|
||||
| **Install (forks)** | [Open VSX](https://open-vsx.org/extension/diegosouzapw/omnicopilot) — Cursor, Windsurf, VSCodium, Theia, code-server, Gitpod, Antigravity, Kiro |
|
||||
| **Source / issues** | [github.com/diegosouzapw/OmniCopilot](https://github.com/diegosouzapw/OmniCopilot) (MIT) |
|
||||
| **Requires** | VS Code 1.104+ |
|
||||
|
||||
> **No Copilot subscription needed.** Since VS Code 1.122 a language-model provider works
|
||||
> without a GitHub sign-in and without any Copilot plan. Inline completions and
|
||||
> embeddings-based features stay outside the provider API and still require Copilot.
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
1. **Run OmniRoute** — `npm install -g omniroute && omniroute` (dashboard on `http://localhost:20128`).
|
||||
2. **Install the extension** — search "OmniRoute" in the Extensions view.
|
||||
3. **Pick a model** — Copilot Chat → model picker → **Manage Models…** → **OmniRoute**, then tick
|
||||
what you want.
|
||||
|
||||
Nothing to configure when OmniRoute runs on the default port. For a remote instance, open the
|
||||
**OmniRoute icon in the Activity Bar** (or run `OmniRoute: Manage Connection`) and set:
|
||||
|
||||
- **Server URL** — the server root, e.g. `http://192.168.0.15:20128`. The `/v1` suffix is
|
||||
appended by the extension; do not include it.
|
||||
- **API key** — only when the server sets `REQUIRE_API_KEY`. Stored in the OS keychain via VS
|
||||
Code SecretStorage, never in `settings.json`.
|
||||
|
||||
---
|
||||
|
||||
## What the picker will show
|
||||
|
||||
The extension does not show the raw `GET /v1/models` payload — it shapes it, and the count you
|
||||
see is lower than the catalog size for two deliberate reasons.
|
||||
|
||||
### It asks for one id per model
|
||||
|
||||
`MODELS_CATALOG_PREFIX_MODE` defaults to **`dual`**, which advertises every model twice — once
|
||||
under the short alias prefix and once under the canonical provider prefix — so older client
|
||||
configs keep resolving either form:
|
||||
|
||||
```
|
||||
cc/claude-sonnet-4-6 ← alias prefix
|
||||
claude/claude-sonnet-4-6 ← canonical prefix, same model
|
||||
```
|
||||
|
||||
The extension requests **`GET /v1/models?prefix=alias`** so one id arrives per model, without
|
||||
changing the server-wide setting for your other clients. On a reference instance this collapsed
|
||||
**2345 entries to 1396 — 949 duplicates, zero models lost.**
|
||||
|
||||
If you would rather fix it server-wide for *every* client, set the
|
||||
`MODELS_CATALOG_PREFIX_MODE` feature flag to `alias` in the dashboard. See
|
||||
[API_REFERENCE → prefix](../reference/API_REFERENCE.md#model-id-prefixes-prefix) for the
|
||||
query parameter and the warning about `canonical`.
|
||||
|
||||
### It hides models that cannot chat
|
||||
|
||||
The catalog also lists image, video, audio, rerank, embedding and moderation models. Those are
|
||||
rejected on a chat request anyway:
|
||||
|
||||
```
|
||||
HTTP 400 — Model '<id>' is an image-generation model and cannot be used on
|
||||
/v1/chat/completions. Use POST /v1/images/generations instead.
|
||||
```
|
||||
|
||||
so they are filtered out by their `type` field before reaching the picker. **Responses-API
|
||||
models are kept** — every Codex / GPT-5.x entry advertises `supported_endpoints: ["responses"]`,
|
||||
and OmniRoute translates those for `/v1/chat/completions`, so they are perfectly usable.
|
||||
|
||||
### Providers you never configured
|
||||
|
||||
The catalog lists models from providers with an **active connection** *plus* every **noAuth**
|
||||
provider — the keyless ones that make up much of the free tier. That is intentional. To hide
|
||||
them, add them to `blockedProviders` in the dashboard settings; nothing changes in the
|
||||
extension.
|
||||
|
||||
---
|
||||
|
||||
## Dashboard inside a VS Code tab
|
||||
|
||||
`omnicopilot.dashboardOpen: "editor"` renders the OmniRoute dashboard in an editor tab via the
|
||||
Simple Browser instead of an external browser. Embedding is **opt-in on the server**: start
|
||||
OmniRoute with
|
||||
|
||||
```bash
|
||||
DASHBOARD_ALLOW_EMBED=vscode omniroute
|
||||
```
|
||||
|
||||
which serves the HTML pages with `frame-ancestors 'self' vscode-webview:` instead of the default
|
||||
`frame-ancestors 'none'` + `X-Frame-Options: DENY`. The API surface (`/api`, `/v1`, `/v1beta`,
|
||||
`/a2a`, `/healthz`) keeps the strict headers either way. Without the variable the page refuses to
|
||||
frame and the extension falls back to the external browser — nothing breaks. See
|
||||
[`ENVIRONMENT.md`](../reference/ENVIRONMENT.md) and issue
|
||||
[#10273](https://github.com/diegosouzapw/OmniRoute/issues/10273).
|
||||
|
||||
---
|
||||
|
||||
## Configuring your other tools from inside VS Code
|
||||
|
||||
**`OmniRoute: Configure Coding CLI`** drives the `omniroute` CLI to write ready-to-use profiles
|
||||
for Codex CLI, Claude Code, Cline, Continue, Cursor, Aider, OpenCode, Goose, Crush, Qwen Code,
|
||||
Kilo and Roo — the same configs described in
|
||||
[`CLI-INTEGRATIONS.md`](CLI-INTEGRATIONS.md). The API key is handed to the CLI through the
|
||||
`OMNIROUTE_API_KEY` environment variable, never on the command line.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Cause / fix |
|
||||
| --- | --- |
|
||||
| No OmniRoute models in the picker | Server unreachable. The status-bar dot goes grey; run `OmniRoute: Check Connection`. Discovery is silent by design and contributes no models rather than prompting. |
|
||||
| Every model appears twice | You are on an OmniCopilot older than 1.0.1 — update. The extension now requests `?prefix=alias`. |
|
||||
| An image/audio model used to be listed and is gone | Intentional since 1.0.1 — it could never answer a chat request. |
|
||||
| Panel missing from the Activity Bar | VS Code moves extra view containers into the **"…"** overflow at the bottom of the Activity Bar, and a container hidden via right-click stays hidden. Right-click the Activity Bar → tick **OmniRoute**, or open it with `OmniRoute: Manage Connection`. |
|
||||
| Dashboard opens in the browser despite `editor` mode | The server is not started with `DASHBOARD_ALLOW_EMBED=vscode` (see above). The fallback is deliberate. |
|
||||
| Models list is stale after changing providers | `OmniRoute: Refresh Models`, or the ↻ link in the panel. |
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
- [`CLI-INTEGRATIONS.md`](CLI-INTEGRATIONS.md) — every other coding tool
|
||||
- [`REMOTE-MODE.md`](REMOTE-MODE.md) — driving a remote OmniRoute
|
||||
- [`../reference/API_REFERENCE.md`](../reference/API_REFERENCE.md) — the `/v1/models` contract
|
||||
- [`docs/CATALOG.md`](https://github.com/diegosouzapw/OmniCopilot/blob/main/docs/CATALOG.md) — the extension's own catalog notes
|
||||
@@ -16,6 +16,7 @@
|
||||
"CLAUDE-CODE-CONFIGURATION",
|
||||
"CODEX-CLI-CONFIGURATION",
|
||||
"CLI-INTEGRATIONS",
|
||||
"VSCODE-COPILOT",
|
||||
"MANAGEMENT-AUTH",
|
||||
"REMOTE-MODE",
|
||||
"PWA_GUIDE",
|
||||
|
||||
@@ -270,6 +270,31 @@ Authorization: Bearer your-api-key
|
||||
→ Returns all chat, embedding, and image models + combos in OpenAI format
|
||||
```
|
||||
|
||||
### Model id prefixes (`?prefix=`)
|
||||
|
||||
Most models are advertised under a **provider prefix**. Which prefix you get is controlled by
|
||||
the `MODELS_CATALOG_PREFIX_MODE` feature flag, and can be overridden **per request** with a
|
||||
query parameter — useful for a client that wants a clean list without changing the server-wide
|
||||
setting for everyone else:
|
||||
|
||||
```bash
|
||||
GET /v1/models?prefix=alias # one id per model — the short alias prefix
|
||||
GET /v1/models?prefix=dual # both forms (server default)
|
||||
GET /v1/models?prefix=canonical # only the full provider-id prefix
|
||||
```
|
||||
|
||||
| Mode | Emits | Notes |
|
||||
| --- | --- | --- |
|
||||
| `dual` | `cc/claude-sonnet-4-6` **and** `claude/claude-sonnet-4-6` | **Default.** Both ids route to the same model; kept so client configs that hardcoded either form keep working. Roughly doubles the catalog. |
|
||||
| `alias` | `cc/claude-sonnet-4-6` | One entry per model. Providers without a distinct alias still emit their entry, so nothing is lost. |
|
||||
| `canonical` | `claude/claude-sonnet-4-6` | ⚠️ The canonical row is only emitted when the canonical provider id **differs** from the alias, so providers without a distinct alias emit nothing in this mode. Prefer `alias` for a de-duplicated list. |
|
||||
|
||||
A `dual`-mode mirror can also be recognised without the query parameter: it carries a `parent`
|
||||
field pointing at the primary id.
|
||||
|
||||
Clients that render a model picker should request `?prefix=alias` — this is what the
|
||||
[OmniCopilot VS Code extension](../guides/VSCODE-COPILOT.md) does.
|
||||
|
||||
### No-thinking model variants
|
||||
|
||||
For thinking-capable Claude models, `/v1/models` also advertises a **no-thinking** variant whose id is prefixed with `claude-3-omniroute-no-thinking/`:
|
||||
|
||||
@@ -881,6 +881,7 @@ Automatic model pricing data synchronization from external sources.
|
||||
| Variable | Default | Source File | Description |
|
||||
| ------------------------- | ------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `ARENA_ELO_SYNC_ENABLED` | `true` | `src/shared/constants/featureFlagDefinitions.ts` | Periodic Arena AI leaderboard ELO sync, configurable from Dashboard Feature Flags or with `false` to opt out. |
|
||||
| `MODELS_CATALOG_PREFIX_MODE` | `dual` | `src/shared/constants/featureFlagDefinitions.ts`, `src/app/api/v1/models/catalog.ts` | Prefix form used for model ids in `GET /v1/models`. `dual` advertises both the short alias prefix and the canonical provider prefix for every model (backward compatibility — roughly doubles the catalog); `alias` emits one id per model; `canonical` emits only the full provider-id prefix and omits providers whose alias already is the canonical id. Clients can override per request with `?prefix=alias`. See [API_REFERENCE](API_REFERENCE.md#model-id-prefixes-prefix). |
|
||||
| `ARENA_ELO_SYNC_INTERVAL` | `86400` (24h) | `src/lib/arenaEloSync.ts` | Sync interval in seconds. |
|
||||
|
||||
---
|
||||
|
||||
@@ -114,6 +114,12 @@ const ENV_VAR_ALLOWLIST = new Set([
|
||||
"LINUX_GPG_KEY", // electron AppImage signing key, CI/build only (ELECTRON_GUIDE.md)
|
||||
"BRANCH_LOCK_TOKEN", // release branch-protection ops token (QUALITY_GATE_PLAYBOOK.md)
|
||||
"NEXT_LOCALE", // next-intl locale cookie name (I18N.md)
|
||||
// Feature flags are resolved by key at runtime — `resolveFeatureFlag()` reads
|
||||
// `process.env[key]` (src/shared/utils/featureFlags.ts), never a literal
|
||||
// `process.env.MODELS_CATALOG_PREFIX_MODE`, so this scan cannot see the read.
|
||||
// The flag is real: defined in featureFlagDefinitions.ts, overridable from the
|
||||
// dashboard or the environment. (API_REFERENCE.md, VSCODE-COPILOT.md)
|
||||
"MODELS_CATALOG_PREFIX_MODE",
|
||||
// Telegram Mini App integration (proposal TELEGRAM-MINIAPP.md, not yet implemented): env vars named in the feasibility analysis but no code reads them yet.
|
||||
"TELEGRAM_WEBHOOK_URL", // proposal-only: Telegram webhook public endpoint (TELEGRAM-MINIAPP.md, future feature)
|
||||
"TELEGRAM_WEBHOOK_SECRET", // proposal-only: Telegram webhook HMAC secret (TELEGRAM-MINIAPP.md, future feature)
|
||||
|
||||
Reference in New Issue
Block a user