OpenCode Integration (Español)

Vía 1 — Generador de CLI (sin instalar npm)

Recomendada para usuarios finales. Se incluye con OmniRoute. Escribe opencode.json directamente.

# Después de instalar OmniRoute (npm i -g @omniroute/cli o mediante un clon local)
omniroute config opencode \
  --base-url http://localhost:20128 \
  --api-key "$OMNIROUTE_API_KEY"

Internamente, la CLI llama a mergeOpenCodeConfigText() (src/shared/services/opencodeConfig.ts:104), por lo que un archivo opencode.json existente conserva sus demás proveedores y comentarios. La entrada de OmniRoute se añade o reemplaza de forma atómica.

Archivo resultante (catálogo de modelos predeterminado):

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

---

Vía 2 — Paquete npm @omniroute/opencode-provider

Recomendada cuando se automatiza la configuración desde Node/TS (canalizaciones de CI, monorepositorios, flujos de instalación personalizados).

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",
  // Opcional: sustituya el catálogo de modelos expuesto a OpenCode
  models: ["auto", "claude-opus-4-7", "gpt-5.5"],
  modelLabels: { auto: "Auto-Combo" },
});

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

Para realizar una combinación no destructiva con un archivo existente, replique mergeOpenCodeConfigText() desde opencodeConfig.ts o invoque el generador de la CLI.

Consulte el README del paquete para conocer la API completa.

---

Qué hace realmente el entorno de ejecución

Ambas vías generan el mismo valor provider.omniroute.npm: "@ai-sdk/openai-compatible". Durante la ejecución, OpenCode carga @ai-sdk/openai-compatible (que ya es una dependencia transitiva de OpenCode) y lo configura con baseURL + apiKey. A partir de ahí:

Interfaz/agente de OpenCode
   → @ai-sdk/openai-compatible
      → HTTP POST {baseURL}/chat/completions          (interfaz de OmniRoute compatible con OpenAI)
         → Manejador /v1/chat/completions de OmniRoute     (open-sse/handlers/chatCore.ts)
            → enrutamiento combinado / Auto-Combo / ejecutor
               → proveedor ascendente

El complemento nunca interactúa con HTTP. Solo genera la configuración.

---

Valores predeterminados del catálogo de modelos

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;

Puedes sobrescribirlos mediante models: [...]. Adiciones recomendadas:

• "auto" — expone Auto-Combo de OmniRoute, el enrutador sin configuración. Permite que OpenCode elija «el mejor modelo disponible» sin que tengas que codificar de forma fija el catálogo.
• "<combo-name>" — cualquier combinación que hayas definido en el panel; OmniRoute la resuelve de forma transparente.

---

Normalización de URL

La función auxiliar acepta ambos formatos y genera exactamente un /v1:

Entrada	Salida (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

Esta deduplicación es el problema más común observado en configuraciones antiguas. Si tienes un opencode.json anterior a v3.8.0 que apunta a /v1/v1/..., vuelve a ejecutar el generador o llama de nuevo a createOmniRouteProvider.

---

Modos de autenticación

Configuración de OmniRoute	Valor recomendado de apiKey
REQUIRE_API_KEY=false (predeterminado localmente)	sk_omniroute (marcador de posición literal)
REQUIRE_API_KEY=true	Una clave de API real por usuario de Panel → Claves de API.

Para los clientes de estilo Anthropic que envían x-api-key + anthropic-version, extractApiKey de OmniRoute también acepta la clave de x-api-key. OpenCode utiliza la interfaz de OpenAI, por lo que siempre enviará Authorization: Bearer ${apiKey}; en este caso no se aplica ningún tratamiento especial para Anthropic.

---

Solución de problemas

Síntoma	Causa	Solución
404 en cada solicitud cuya URL contiene /v1/v1/	Configuración obsoleta de un complemento anterior a v3.8 que añadía /v1 dos veces.	Vuelve a generarla mediante la Ruta 1 o 2.
401 Invalid API key	OmniRoute tiene REQUIRE_API_KEY=true y la clave es desconocida.	Crea la clave en el panel o establece REQUIRE_API_KEY=false (solo localmente) y usa sk_omniroute.
Lista de modelos vacía en la interfaz de OpenCode	Los 4 modelos predeterminados están ocultos en la visibilidad de proveedores de OmniRoute.	Usa models: ["auto", ...] para mostrar los que hayas habilitado.
Error 500 de OpenCode con cannot read property 'models'	Las versiones antiguas de OpenCode (< 0.1.x) no aceptaban models en línea.	Actualiza OpenCode a una versión que siga el esquema v1 (opencode.ai/config.json).

---

Véase también

• Referencia de la API — superficie REST completa de OmniRoute
• Auto-Combo — qué significa model: "auto"
• README de @omniroute/opencode-provider
• Código fuente: src/shared/services/opencodeConfig.ts, src/lib/cli-helper/config-generator/opencode.ts, @omniroute/opencode-provider/src/index.ts

---

Código fuente de OmniRoute (a58000c7685f)