OpenCode Integration (Português (Brasil))

Caminho 1 — Gerador via CLI (sem instalar via npm)

Recomendado para usuários finais. Incluído no OmniRoute. Grava opencode.json no local.

# Após instalar o OmniRoute (npm i -g @omniroute/cli ou clone local)
omniroute config opencode \
  --base-url http://localhost:20128 \
  --api-key "$OMNIROUTE_API_KEY"

Nos bastidores, a CLI chama mergeOpenCodeConfigText() (src/shared/services/opencodeConfig.ts:104), portanto um opencode.json existente mantém seus outros provedores e comentários. A entrada do OmniRoute é adicionada/substituída de forma atômica.

Arquivo resultante (catálogo de modelos padrão):

{
  "$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" },
      },
    },
  },
}

---

Caminho 2 — Pacote npm @omniroute/opencode-provider

Recomendado ao gerar a configuração por scripts em Node/TS (pipelines de CI, monorepos, fluxos de instalação 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: substitua o catálogo de modelos exposto ao OpenCode
  models: ["auto", "claude-opus-4-7", "gpt-5.5"],
  modelLabels: { auto: "Auto-Combo" },
});

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

Para uma mesclagem não destrutiva com um arquivo existente, replique mergeOpenCodeConfigText() de opencodeConfig.ts ou chame o gerador via CLI.

Consulte o README do pacote para ver a API completa.

---

O que o runtime realmente faz

Ambos os caminhos produzem o mesmo provider.omniroute.npm: "@ai-sdk/openai-compatible". Durante a execução, o OpenCode carrega @ai-sdk/openai-compatible (que já é uma dependência transitiva do OpenCode) e o configura com baseURL + apiKey. A partir daí:

UI/agente do OpenCode
   → @ai-sdk/openai-compatible
      → HTTP POST {baseURL}/chat/completions          (interface OpenAI do OmniRoute)
         → manipulador /v1/chat/completions do OmniRoute     (open-sse/handlers/chatCore.ts)
            → roteamento combinado / Auto-Combo / executor
               → provedor upstream

O plugin nunca interage diretamente com HTTP. Ele apenas gera a configuração.

---

Padrões do 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;

Você pode substituir esses valores usando models: [...]. Adições recomendadas:

• "auto" — disponibiliza o roteador Auto-Combo do OmniRoute, que não exige configuração. Permite que o OpenCode escolha “o melhor modelo disponível” sem que você precise codificar o catálogo diretamente.
• "<combo-name>" — qualquer combinação que você tenha definido no painel; o OmniRoute a resolve de forma transparente.

---

Normalização de URL

O auxiliar aceita ambos os formatos e gera exatamente um /v1:

Entrada	Saída (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

Essa deduplicação é a causa mais comum de falhas observada em configurações antigas. Se você tiver um opencode.json anterior à v3.8.0 que aponte para /v1/v1/..., execute novamente o gerador ou chame createOmniRouteProvider outra vez.

---

Modos de autenticação

Configuração do OmniRoute	Valor recomendado de apiKey
REQUIRE_API_KEY=false (padrão para ambiente local)	sk_omniroute (placeholder literal)
REQUIRE_API_KEY=true	Uma chave de API real por usuário obtida em Painel → Chaves de API.

Para clientes no estilo Anthropic que enviam x-api-key + anthropic-version, o extractApiKey do OmniRoute também aceita a chave de x-api-key. O OpenCode usa a interface do OpenAI, portanto sempre enviará Authorization: Bearer ${apiKey} — nenhum caso especial do Anthropic se aplica aqui.

---

Solução de problemas

Sintoma	Causa	Correção
404 em todas as solicitações com URL contendo /v1/v1/	Configuração obsoleta de um plugin anterior à v3.8 que adicionava /v1 duas vezes.	Gere-a novamente por meio do Caminho 1 ou 2.
401 Invalid API key	O OmniRoute está com REQUIRE_API_KEY=true e a chave é desconhecida.	Crie a chave no painel ou defina REQUIRE_API_KEY=false (somente em ambiente local) e use sk_omniroute.
Lista de modelos vazia na interface do OpenCode	Todos os 4 modelos padrão estão ocultos na visibilidade de provedores do OmniRoute.	Passe models: ["auto", ...] para disponibilizar aqueles que você habilitou.
Erro 500 do OpenCode com cannot read property 'models'	Versões antigas do OpenCode (< 0.1.x) não aceitavam models inline.	Atualize o OpenCode para uma versão compatível com o esquema v1 (opencode.ai/config.json).

---

Veja também

• Referência da API — interface REST completa do OmniRoute
• Auto-Combo — o que model: "auto" significa
• README do @omniroute/opencode-provider
• Código-fonte: src/shared/services/opencodeConfig.ts, src/lib/cli-helper/config-generator/opencode.ts, @omniroute/opencode-provider/src/index.ts

---

Código-fonte do OmniRoute (a58000c7685f)