OpenCode OpenAI-kompatibles Anbieter-Setup: Coding-Agent-Modelle über Flatkey leiten

Ein OpenCode OpenAI-kompatibles Anbieter-Setup ist nützlich, wenn Sie möchten, dass OpenCode mit einer Modellroute kommuniziert, die sich wie die OpenAI Chat Completions API verhält, während Ihr Team den Schlüsselbesitz, das Modell-Routing und die Nutzungsüberprüfung in einem einzigen Gateway behält.

Der wichtige Teil ist, dass OpenCode einen dokumentierten Pfad für benutzerdefinierte Anbieter hat. In den OpenCode-Anbieterdokumenten, die am 8. Juli 2026 überprüft wurden, ist der Ablauf wie folgt: Fügen Sie mit /connect eine Anmeldeinformation hinzu, wählen Sie Other (Andere) für einen Anbieter, der noch nicht aufgeführt ist, geben Sie diesem Anbieter eine einprägsame ID, konfigurieren Sie den Anbieter in opencode.json und führen Sie dann /models aus, um aus den konfigurierten Modellen auszuwählen.

Flatkey passt als Gateway hinter dem Anbieter in dieses Muster. Sie behalten OpenCode als Coding-Agent bei, richten den Anbieter auf die OpenAI-kompatible API-Basis-URL von Flatkey aus und überprüfen, ob der OpenCode-Modellverkehr in den Nutzungs- oder Anforderungsprotokollen von Flatkey erscheint, bevor Sie es zur Standardroute machen.

Schnelle Antwort für das OpenCode OpenAI-kompatible Anbieter-Setup

Verwenden Sie diese Setup-Form, wenn der Modell-Endpunkt mit Chat Completions kompatibel ist.

Diese OpenCode OpenAI-kompatible Anbieter-Anleitung verwendet Vorlagen. Überprüfen Sie die genauen Modellaliase und die Endpunktfamilie mit Ihrem Flatkey-Konto, bevor Sie produktive Arbeit des Coding-Agents weiterleiten.

Was OpenCode benötigt

OpenCode hat zwei separate Zustandsteile für einen benutzerdefinierten Anbieter.

Die OpenCode-Konfiguration kann JSON oder JSONC sein. Sie können sie global unter ~/.config/opencode/opencode.json oder in einem Projektstammverzeichnis als opencode.json platzieren. Die Projektkonfiguration hat eine höhere Standardpriorität, verwenden Sie also eine Projektdatei, wenn Sie Flatkey in einem Repository testen möchten, ohne jeden OpenCode-Arbeitsbereich zu ändern.

Schritt 1: Erstellen Sie einen Flatkey-Schlüssel für OpenCode

Erstellen Sie einen Flatkey-Schlüssel für diesen Workload und notieren Sie drei Werte außerhalb der Quellcodeverwaltung.

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_MODEL=your-current-flatkey-model-alias

Halten Sie das API-Stammverzeichnis vom Endpunktpfad getrennt. Die OpenCode-Anbieterkonfiguration sollte https://router.flatkey.ai/v1 als options.baseURL verwenden; direkte HTTP-Smoke-Tests fügen /chat/completions hinzu.

Bevor Sie OpenCode verbinden, führen Sie einen direkten Test mit demselben Flatkey-Schlüssel und Modellalias durch.

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      { "role": "user", "content": "Antworten Sie mit genau: flatkey route ok" }
    ]
  }'

Wenn diese direkte Anfrage fehlschlägt, korrigieren Sie den Flatkey-Schlüssel, das Modellalias, die Endpunktfamilie oder die Kontoroute, bevor Sie mit dem Debugging von OpenCode beginnen. Ein OpenCode OpenAI-kompatibler Anbieter kann ein Modellalias nicht kompensieren, das das Gateway-Konto nicht aufrufen kann.

Schritt 2: Fügen Sie die Flatkey-Anmeldeinformationen in OpenCode hinzu

OpenCode speichert Anbieter-Anmeldeinformationen über /connect. In der OpenCode-TUI:

/connect

Wählen Sie Other (Andere), geben Sie eine Anbieter-ID wie flatkey ein und fügen Sie dann den Flatkey-API-Schlüssel ein. Fügen Sie die Basis-URL nicht in die Eingabeaufforderung für Anmeldeinformationen ein. Der Schlüssel beweist die Identität; die Basis-URL gehört in opencode.json.

Verwenden Sie eine einfache Anbieter-ID. flatkey ist besser als flatkey-prod-openai-compatible-gateway-v2, da Sie sie in Modell-IDs und Rollback-Notizen eingeben werden.

Schritt 3: Fügen Sie die OpenCode-Anbieterkonfiguration hinzu

Erstellen oder aktualisieren Sie opencode.json im Projektstammverzeichnis, das Sie testen möchten.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "your-current-flatkey-model-alias": {
          "name": "Flatkey primary model"
        }
      }
    }
  },
  "model": "flatkey/your-current-flatkey-model-alias"
}

Dies ist die kleinste Konfiguration für einen OpenCode OpenAI-kompatiblen Anbieter. Sie gibt OpenCode einen Anbieter namens flatkey, weist OpenCode an, das OpenAI-kompatible AI SDK-Paket zu verwenden, und stellt einen Modell-Alias in der Modellauswahl zur Verfügung.

Wenn Sie möchten, dass OpenCode eine kleinere Route für einfachere Aufgaben verwendet, fügen Sie small_model erst hinzu, nachdem die primäre Route funktioniert.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "primary-flatkey-model-alias": {
          "name": "Flatkey primary"
        },
        "lighter-flatkey-model-alias": {
          "name": "Flatkey lightweight"
        }
      }
    }
  },
  "model": "flatkey/primary-flatkey-model-alias",
  "small_model": "flatkey/lighter-flatkey-model-alias"
}

Verwenden Sie die Modell-Aliase, die Ihr Flatkey-Schlüssel tatsächlich aufrufen kann. Wenn Ihr Konto eine authentifizierte /v1/models-Route bereitstellt, vergleichen Sie die konfigurierten Modell-IDs mit dieser Antwort. Andernfalls kopieren Sie Aliase aus dem aktuellen Flatkey-Dashboard oder Modellverzeichnis und überprüfen Sie sie mit einer echten Anfrage.

Schritt 4: Wählen Sie das Modell in OpenCode aus und testen Sie es

Öffnen Sie nach dem Speichern der Konfiguration die Modellauswahl.

/models

Wählen Sie das Flatkey-Anbietermodell aus. Führen Sie dann einen kleinen Prompt in OpenCode aus:

Reply with exactly: opencode flatkey route ok

Verschieben Sie noch keinen ganzen Coding-Workflow. Speichern Sie zuerst ein kompaktes Verifizierungspaket.

Dies verwandelt eine Migration eines OpenCode OpenAI-kompatiblen Anbieters in eine kleine operative Änderung anstelle eines blinden Anbieterwechsels.

Schritt 5: Halten Sie Chat Completions und Responses getrennt

Die Dokumentation für benutzerdefinierte Anbieter von OpenCode weist auf eine Paketgrenze hin: Verwenden Sie @ai-sdk/openai-compatible für OpenAI-kompatible Anbieter, die /v1/chat/completions verwenden; wenn ein Anbieter oder Modell /v1/responses verwendet, nutzen Sie @ai-sdk/openai.

Das bedeutet, dass die erste Flatkey-Route ein Modell im Stil von Chat Completions sein sollte, es sei denn, Sie haben aktuelle Nachweise dafür, dass Ihr ausgewähltes Modell und der Client-Pfad eine andere Endpunktfamilie verwenden.

Verwenden Sie diese Entscheidungstabelle, bevor Sie weitere Modelle hinzufügen.

Beginnen Sie für die meisten Einrichtungsarbeiten mit einer Chat Completions-Route. Fügen Sie Streaming, Tool-Aufrufe und sekundäre Modell-Aliase hinzu, nachdem der erste Smoke-Test des OpenCode OpenAI-kompatiblen Anbieters in Flatkey sichtbar ist.

Schritt 6: Fügen Sie Team-Kontrollen hinzu, nachdem die Route funktioniert

Sobald OpenCode Flatkey aufrufen kann, machen Sie die Route beobachtbar.

An dieser Stelle wird Flatkey mehr als nur eine Basis-URL. Ein funktionierender OpenCode OpenAI-kompatibler Anbieter sollte auch Plattform-, Finanz- und Betriebsteams einen Ort bieten, an dem sie die Modellnutzung überprüfen und die Route ändern können, ohne jeden Entwickler bitten zu müssen, separate Anbieterkonten zu verwalten.

Für eine umfassendere Migrationsplanung kombinieren Sie diesen Leitfaden mit dem Flatkey Leitfaden zur Migration von OpenAI-kompatiblen APIs. Wenn Sie benachbarte Codierungstools vergleichen, sehen Sie sich den Leitfaden für den OpenAI-kompatiblen Anbieter von Continue.dev und den Einrichtungsleitfaden für Roo Code OpenAI-kompatible APIs an.

Fehlerbehebung bei einem OpenCode OpenAI-kompatiblen Anbieter

Wenn die erste Anfrage fehlschlägt, ändern Sie noch keine Prompts, Agenten, Berechtigungen oder den Repository-Code. Halten Sie die Debugging-Oberfläche des OpenCode OpenAI-kompatiblen Anbieters klein: Anmeldeinformationen, Anbieter-ID, Basis-URL, Paket, Modellalias und eine einfache Chat-Anfrage.

Abschließende Checkliste

Bevor Sie Flatkey als Standardroute für OpenCode verwenden, bestätigen Sie:

1. /connect hat eine Flatkey-Anmeldeinformation unter derselben Anbieter-ID, die in opencode.json verwendet wird.
2. provider.flatkey.npm ist @ai-sdk/openai-compatible für die Chat-Completions-Route.
3. provider.flatkey.options.baseURL ist https://router.flatkey.ai/v1.
4. model verweist auf einen konfigurierten flatkey/<modell-alias>-Wert.
5. /models zeigt das konfigurierte Flatkey-Modell an.
6. Ein einzeiliger OpenCode-Prompt wird erfolgreich zurückgegeben.
7. Flatkey-Nutzungs- oder Anforderungsprotokolle zeigen die OpenCode-Testanforderung an.
8. Die vorherige Anbieter-/Modellroute ist für ein Rollback dokumentiert.

Ein OpenCode OpenAI-kompatibles Anbieter-Setup ist abgeschlossen, wenn der Anbieter konfiguriert, auswählbar, in den Flatkey-Protokollen verifiziert und umkehrbar ist. Wenn Sie bereit sind, den Modellverkehr von Codierungsagenten über einen einzigen Schlüssel zu leiten, holen Sie sich einen Flatkey-Schlüssel und beginnen Sie mit einem einzigen risikoarmen OpenCode-Prompt.