OpenCode Integration (日本語)

方法 1 — CLI ジェネレーター（npm install 不要）

エンドユーザーに推奨される方法です。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": "<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 から設定をスクリプトで生成する場合（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));

既存ファイルに対して非破壊的なマージを行うには、opencodeConfig.ts の mergeOpenCodeConfigText() を再現するか、CLI ジェネレーターを呼び出してください。

完全な API については、package README を参照してください。

---

ランタイムが実際に行うこと

どちらの方法でも、同じ provider.omniroute.npm: "@ai-sdk/openai-compatible" が生成されます。ランタイムでは、OpenCode が @ai-sdk/openai-compatible（OpenCode の推移的依存関係としてすでに含まれています）を読み込み、baseURL と apiKey を使用して設定します。その後のフローは次のとおりです。

OpenCode UI/エージェント
   → @ai-sdk/openai-compatible
      → HTTP POST {baseURL}/chat/completions          （OmniRoute の OpenAI インターフェース）
         → 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" — OmniRoute のゼロコンフィグルーターである Auto-Combo を表示します。カタログをハードコードすることなく、OpenCode が「利用可能な最適なモデル」を選択できるようにします。
• "<combo-name>" — ダッシュボードで定義した任意のコンボ。OmniRoute が透過的に解決します。

---

URL の正規化

このヘルパーは両方の形式を受け入れ、/v1 を正確に1つだけ出力します：

入力	出力（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 より前の opencode.json が /v1/v1/... を指している場合は、ジェネレーターを再実行するか、createOmniRouteProvider を再度呼び出してください。

---

認証モード

OmniRoute の設定	推奨される apiKey の値
REQUIRE_API_KEY=false（ローカル環境のデフォルト）	sk_omniroute（リテラルのプレースホルダー）
REQUIRE_API_KEY=true	ダッシュボード → API Keys で取得した実際のユーザー別 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", ...] を渡します。
OpenCode で cannot read property 'models' という 500 エラー	古い OpenCode（< 0.1.x）はインラインの models を受け付けませんでした。	v1 スキーマ（opencode.ai/config.json）に準拠するバージョンへ OpenCode をアップグレードします。

---

関連項目

• API リファレンス — OmniRoute REST API の全仕様
• 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)