OmniRoute/docs/i18n/ru/docs/frameworks/OPENCODE.md

OpenCode Integration (Русский)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Статус: Общедоступно. Аудитория: Операторы, подключающие OpenCode к развертыванию OmniRoute. Источник истины (схема конфигурации): src/shared/services/opencodeConfig.ts Источник истины (пакет npm): @omniroute/opencode-provider/ (публикуемое рабочее пространство)

OpenCode — это агентный ИИ-клиент с интерфейсами CLI и настольного приложения. Он считывает каталог провайдеров из ~/.config/opencode/opencode.json (или opencode.jsonc) и использует схему по адресу https://opencode.ai/config.json. OmniRoute представляет себя в OpenCode как один из таких провайдеров — каждый запрос проходит через стандартный OpenAI-совместимый интерфейс /v1 OmniRoute, поэтому OpenCode автоматически получает преимущества маршрутизации Auto-Combo, автоматических выключателей, политик ключей, наблюдаемости и т. д.

Поддерживаются два способа интеграции. Выберите один из них — оба создают одинаковую конфигурацию.

---

Способ 1 — генератор CLI (без установки npm)

Рекомендуется для конечных пользователей. Поставляется вместе с OmniRoute. Записывает изменения непосредственно в opencode.json.

# После установки OmniRoute (npm i -g @omniroute/cli или локального клонирования)
omniroute config opencode \
  --base-url http://localhost:20128 \
  --api-key "$OMNIROUTE_API_KEY"

Внутри CLI вызывает mergeOpenCodeConfigText() (src/shared/services/opencodeConfig.ts:104), поэтому в существующем opencode.json сохраняются другие провайдеры и комментарии. Запись OmniRoute добавляется или заменяется атомарно.

Полученный файл (каталог моделей по умолчанию):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1",
        "apiKey": "<ваш-ключ>",
      },
      "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 — пакет npm @omniroute/opencode-provider

Рекомендуется при создании конфигурации с помощью скриптов Node/TS (конвейеры CI, монорепозитории, пользовательские сценарии установки).

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",
  // Необязательно: переопределите каталог моделей, доступный в OpenCode
  models: ["auto", "claude-opus-4-7", "gpt-5.5"],
  modelLabels: { auto: "Auto-Combo" },
});

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

Для неразрушающего объединения с существующим файлом воспроизведите mergeOpenCodeConfigText() из opencodeConfig.ts или вызовите генератор CLI.

Полное описание API см. в README пакета.

---

Что фактически делает среда выполнения

Оба способа создают одинаковое значение provider.omniroute.npm: "@ai-sdk/openai-compatible". Во время выполнения OpenCode загружает @ai-sdk/openai-compatible (уже являющийся транзитивной зависимостью OpenCode) и настраивает его с помощью baseURL + apiKey. Далее:

Интерфейс/агент OpenCode
   → @ai-sdk/openai-compatible
      → HTTP POST {baseURL}/chat/completions          (OpenAI-совместимый интерфейс OmniRoute)
         → обработчик OmniRoute /v1/chat/completions  (open-sse/handlers/chatCore.ts)
            → комбинированная маршрутизация / Auto-Combo / исполнитель
               → вышестоящий провайдер

Плагин никогда не работает с HTTP напрямую. Он лишь создает конфигурацию.

---

Модели каталога по умолчанию

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;

Значения можно переопределить с помощью models: [...]. Рекомендуемые дополнения:

• "auto" — предоставляет маршрутизатор Auto-Combo от OmniRoute, не требующий настройки. Позволяет OpenCode выбрать «лучшую доступную модель» без жёсткого задания каталога.
• "<combo-name>" — любая комбинация, определённая вами на панели управления; OmniRoute обрабатывает её прозрачно.

---

Нормализация URL

Вспомогательная функция принимает обе формы и добавляет ровно один /v1:

Вход	Выход (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

Эта дедупликация устраняет наиболее распространённую причину сбоев в старых конфигурациях. Если у вас есть opencode.json, созданный до v3.8.0 и указывающий на /v1/v1/..., повторно запустите генератор или снова вызовите createOmniRouteProvider.

---

Режимы аутентификации

Настройка OmniRoute	Рекомендуемое значение apiKey
REQUIRE_API_KEY=false (по умолчанию локально)	sk_omniroute (буквальное значение-заполнитель)
REQUIRE_API_KEY=true	Настоящий пользовательский API-ключ из панели управления → API Keys.

Для клиентов в стиле Anthropic, отправляющих x-api-key + anthropic-version, функция extractApiKey OmniRoute также учитывает ключ из x-api-key. OpenCode использует интерфейс OpenAI, поэтому всегда отправляет Authorization: Bearer ${apiKey} — особая обработка Anthropic здесь не применяется.

---

Устранение неполадок

Симптом	Причина	Решение
404 для каждого запроса с URL, содержащим /v1/v1/	Устаревшая конфигурация плагина до v3.8, дважды добавляющая суффикс /v1.	Повторно создайте конфигурацию с помощью способа 1 или 2.
401 Invalid API key	В OmniRoute установлено REQUIRE_API_KEY=true, и ключ неизвестен.	Создайте ключ на панели управления или установите REQUIRE_API_KEY=false (только локально) и используйте sk_omniroute.
Список моделей в интерфейсе OpenCode пуст	Все 4 модели по умолчанию скрыты настройками видимости провайдера OmniRoute.	Передайте models: ["auto", ...], чтобы отобразить включённые вами модели.
Ошибка OpenCode 500 с cannot read property 'models'	Старые версии OpenCode (< 0.1.x) не поддерживали встроенное поле models.	Обновите OpenCode до версии, соответствующей схеме v1 (opencode.ai/config.json).

---

См. также

• Справочник API — полное описание OmniRoute REST
• Auto-Combo — что означает model: "auto"
• README @omniroute/opencode-provider
• Исходный код: src/shared/services/opencodeConfig.ts, src/lib/cli-helper/config-generator/opencode.ts, @omniroute/opencode-provider/src/index.ts