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

OpenCode Integration (Bahasa Indonesia)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇳🇬 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 · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Status: Tersedia secara umum. Audiens: Operator yang menghubungkan OpenCode ke deployment OmniRoute. Sumber kebenaran (skema konfigurasi): src/shared/services/opencodeConfig.ts Sumber kebenaran (paket npm): @omniroute/opencode-provider/ (workspace yang dapat dipublikasikan)

OpenCode adalah klien AI agentik berbasis CLI/desktop. OpenCode membaca katalog penyedianya dari ~/.config/opencode/opencode.json (atau opencode.jsonc) dan mengikuti skema di https://opencode.ai/config.json. OmniRoute mengekspos dirinya kepada OpenCode sebagai salah satu penyedia tersebut — setiap permintaan mengalir melalui antarmuka /v1 standar OmniRoute yang kompatibel dengan OpenAI, sehingga OpenCode secara otomatis mendapatkan manfaat dari perutean Auto-Combo, circuit breaker, kebijakan kunci, observabilitas, dan sebagainya.

Ada dua jalur integrasi yang didukung. Pilih salah satu — keduanya menghasilkan konfigurasi yang sama.

---

Jalur 1 — Generator CLI (tanpa instalasi npm)

Direkomendasikan untuk pengguna akhir. Disertakan bersama OmniRoute. Menulis opencode.json secara langsung.

# Setelah menginstal OmniRoute (npm i -g @omniroute/cli atau clone lokal)
omniroute config opencode \
  --base-url http://localhost:20128 \
  --api-key "$OMNIROUTE_API_KEY"

Di balik layar, CLI memanggil mergeOpenCodeConfigText() (src/shared/services/opencodeConfig.ts:104), sehingga opencode.json yang sudah ada tetap mempertahankan penyedia lain dan komentarnya. Entri OmniRoute ditambahkan/diganti secara atomik.

File yang dihasilkan (katalog model default):

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

---

Jalur 2 — Paket npm @omniroute/opencode-provider

Direkomendasikan saat Anda membuat skrip konfigurasi dari Node/TS (pipeline CI, monorepo, alur penginstal kustom).

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",
  // Opsional: timpa katalog model yang diekspos ke OpenCode
  models: ["auto", "claude-opus-4-7", "gpt-5.5"],
  modelLabels: { auto: "Auto-Combo" },
});

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

Untuk penggabungan non-destruktif dengan file yang sudah ada, replikasi mergeOpenCodeConfigText() dari opencodeConfig.ts atau panggil generator CLI.

Lihat README paket untuk API selengkapnya.

---

Apa yang sebenarnya dilakukan runtime

Kedua jalur menghasilkan provider.omniroute.npm: "@ai-sdk/openai-compatible" yang sama. Saat runtime, OpenCode memuat @ai-sdk/openai-compatible (yang sudah menjadi dependensi transitif OpenCode) dan mengonfigurasinya dengan baseURL + apiKey. Dari sana:

UI/agen OpenCode
   → @ai-sdk/openai-compatible
      → HTTP POST {baseURL}/chat/completions          (antarmuka OpenAI OmniRoute)
         → handler /v1/chat/completions OmniRoute     (open-sse/handlers/chatCore.ts)
            → perutean kombo / Auto-Combo / eksekutor
               → penyedia upstream

Plugin tidak pernah berinteraksi langsung dengan HTTP. Plugin hanya menghasilkan konfigurasi.

---

Default katalog model

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;

Anda dapat menggantinya melalui models: [...]. Penambahan yang direkomendasikan:

• "auto" — menampilkan router Auto-Combo tanpa konfigurasi milik OmniRoute. Memungkinkan OpenCode memilih "model terbaik yang tersedia" tanpa harus menetapkan katalog secara langsung.
• "<combo-name>" — kombo apa pun yang telah Anda definisikan di dasbor; OmniRoute akan menanganinya secara transparan.

---

Normalisasi URL

Helper menerima kedua bentuk dan menghasilkan tepat satu /v1:

Input	Output (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

Deduplikasi ini adalah penyebab kerusakan yang paling umum pada konfigurasi lama. Jika Anda memiliki opencode.json dari sebelum v3.8.0 yang mengarah ke /v1/v1/..., jalankan ulang generator atau panggil kembali createOmniRouteProvider.

---

Mode autentikasi

Pengaturan OmniRoute	Nilai apiKey yang direkomendasikan
REQUIRE_API_KEY=false (default untuk lokal)	sk_omniroute (placeholder literal)
REQUIRE_API_KEY=true	Kunci API per pengguna yang sebenarnya dari Dasbor → Kunci API.

Untuk klien bergaya Anthropic yang mengirim x-api-key + anthropic-version, extractApiKey milik OmniRoute juga menerima kunci dari x-api-key. OpenCode menggunakan antarmuka OpenAI, sehingga akan selalu mengirim Authorization: Bearer ${apiKey} — tidak ada perlakuan khusus Anthropic yang berlaku di sini.

---

Pemecahan masalah

Gejala	Penyebab	Perbaikan
404 pada setiap permintaan dengan URL berisi /v1/v1/	Konfigurasi usang dari plugin sebelum v3.8 yang menambahkan sufiks /v1 dua kali.	Buat ulang melalui Jalur 1 atau 2.
401 Invalid API key	OmniRoute memiliki REQUIRE_API_KEY=true dan kunci tersebut tidak dikenal.	Buat kunci di dasbor, atau atur REQUIRE_API_KEY=false (khusus lokal) dan gunakan sk_omniroute.
Daftar model kosong di UI OpenCode	Keempat model default disembunyikan dalam visibilitas penyedia OmniRoute.	Teruskan models: ["auto", ...] untuk menampilkan model yang telah Anda aktifkan.
OpenCode 500 dengan cannot read property 'models'	OpenCode versi lama (< 0.1.x) tidak menerima models inline.	Tingkatkan OpenCode ke versi yang mengikuti skema v1 (opencode.ai/config.json).

---

Lihat juga

• Referensi API — keseluruhan antarmuka REST OmniRoute
• Auto-Combo — arti model: "auto"
• @omniroute/opencode-provider README
• Sumber: src/shared/services/opencodeConfig.ts, src/lib/cli-helper/config-generator/opencode.ts, @omniroute/opencode-provider/src/index.ts