OpenCode Integration (한국어)

경로 1 — CLI 생성기(npm 설치 불필요)

최종 사용자에게 권장됩니다. OmniRoute와 함께 제공되며 기존 위치에 opencode.json을 작성합니다.

# OmniRoute 설치 후(npm i -g @omniroute/cli 또는 로컬 clone)
omniroute config opencode \
  --base-url http://localhost:20128 \
  --api-key "$OMNIROUTE_API_KEY"

내부적으로 CLI는 mergeOpenCodeConfigText()(src/shared/services/opencodeConfig.ts:104)를 호출하므로 기존 opencode.json의 다른 provider와 주석이 유지됩니다. OmniRoute 항목은 원자적으로 추가되거나 교체됩니다.

생성되는 파일(기본 model 카탈로그):

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

---

경로 2 — npm package @omniroute/opencode-provider

Node/TS에서 config를 스크립트로 생성하는 경우(CI pipeline, monorepo, 사용자 지정 installer flow) 권장됩니다.

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에 노출되는 model 카탈로그 재정의
  models: ["auto", "claude-opus-4-7", "gpt-5.5"],
  modelLabels: { auto: "Auto-Combo" },
});

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

기존 파일에 비파괴 방식으로 병합하려면 opencodeConfig.ts의 mergeOpenCodeConfigText()를 재현하거나 CLI 생성기를 호출하세요.

전체 API는 package README를 참조하세요.

---

runtime에서 실제로 수행되는 작업

두 경로 모두 동일한 provider.omniroute.npm: "@ai-sdk/openai-compatible"을 생성합니다. runtime에서 OpenCode는 @ai-sdk/openai-compatible(이미 OpenCode의 transitive dependency)을 로드하고 baseURL + apiKey로 구성합니다. 이후 흐름은 다음과 같습니다.

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

plugin은 HTTP를 전혀 처리하지 않습니다. 오직 configuration만 생성합니다.

---

모델 카탈로그 기본값

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" — OmniRoute의 Auto-Combo 무설정 라우터를 표시합니다. 카탈로그를 하드 코딩하지 않아도 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

이 중복 제거 문제는 이전 구성에서 나타나는 가장 흔한 오류입니다. v3.8.0 이전에 생성되었으며 /v1/v1/...을 가리키는 opencode.json이 있다면 생성기를 다시 실행하거나 createOmniRouteProvider를 다시 호출하세요.

---

인증 모드

OmniRoute 설정	권장 apiKey 값
REQUIRE_API_KEY=false (로컬 환경의 기본값)	sk_omniroute (리터럴 자리 표시자)
REQUIRE_API_KEY=true	대시보드 → API 키에서 발급한 실제 사용자별 API 키입니다.

x-api-key와 anthropic-version을 전송하는 Anthropic 스타일 클라이언트의 경우, OmniRoute의 extractApiKey는 x-api-key의 키도 인식합니다. OpenCode는 OpenAI 인터페이스를 사용하므로 항상 Authorization: Bearer ${apiKey}를 전송합니다. 따라서 여기에는 Anthropic 관련 특수 처리가 적용되지 않습니다.

---

문제 해결

증상	원인	해결 방법
/v1/v1/이 포함된 URL의 모든 요청에서 404 발생	/v1을 이중으로 추가하던 v3.8 이전 플러그인의 오래된 구성입니다.	경로 1 또는 2를 통해 다시 생성하세요.
401 Invalid API key	OmniRoute에서 REQUIRE_API_KEY=true로 설정되어 있으며 키를 인식할 수 없습니다.	대시보드에서 키를 생성하거나 REQUIRE_API_KEY=false로 설정한 후(로컬 전용) sk_omniroute를 사용하세요.
OpenCode UI에서 모델 목록이 비어 있음	4개의 기본 모델이 모두 OmniRoute의 제공자 표시 설정에서 숨겨져 있습니다.	활성화한 모델을 표시하려면 models: ["auto", ...]를 전달하세요.
cannot read property 'models'와 함께 OpenCode 500 발생	이전 OpenCode(< 0.1.x)는 인라인 models를 허용하지 않았습니다.	v1 스키마(opencode.ai/config.json)를 따르는 버전으로 OpenCode를 업그레이드하세요.

---

함께 보기

• API 참조 — OmniRoute REST 전체 범위
• Auto-Combo — model: "auto"의 의미
• @omniroute/opencode-provider README
• 소스: src/shared/services/opencodeConfig.ts, src/lib/cli-helper/config-generator/opencode.ts, @omniroute/opencode-provider/src/index.ts

---

OmniRoute 소스 코드 (a58000c7685f)