OpenCode in Russland: API-Einrichtung und erste Anfrage

Was für den Start von OpenCode in Russland nötig ist

OpenCode ist ein Coding-Agent für das Terminal. Er liest Projektdateien, arbeitet mit dem ausgewählten Modell und kann Aktionen im Repository ausführen. Für den ersten Start benötigen Sie:

• macOS, Linux oder Windows mit Zugang zu einer offiziellen Installationsmethode;
• einen eigenen BetterToken API Key;
• die aktuelle Model ID aus dem BetterToken-Modellkatalog;
• ein Testverzeichnis, in dem Sie die Antwort des Agenten gefahrlos prüfen können.

BetterToken ist in diesem Aufbau für die externe API-Anfrage zuständig. Die Verfügbarkeit der OpenCode-Website, der Installationsdatei, von GitHub oder von Updates wird dadurch nicht garantiert. Aus Russland können Sie sich ohne VPN mit dem BetterToken API Endpoint verbinden; dies gilt nicht für Websites und Downloads von Drittanbietern.

OpenCode aus einer offiziellen Quelle installieren

Wählen Sie eine Methode. Node.js ist nur für die Installation über npm erforderlich.

macOS und Linux: offizieller Installer

curl -fsSL https://opencode.ai/install | bash

npm

npm install -g opencode-ai

Homebrew

brew install anomalyco/tap/opencode

OpenCode empfiehlt den eigenen Tap, weil sich die von Homebrew gepflegte Formel brew install opencode später ändern kann.

Windows

Die offizielle Dokumentation nennt Chocolatey oder Scoop:

choco install opencode

scoop install opencode

Prüfen Sie nach der Installation, ob der Befehl verfügbar ist:

opencode --version

Die Version sollte ohne command not found ausgegeben werden. Eine konkrete Versionsnummer wird hier nicht festgeschrieben, weil sie sich mit Releases ändert.

Wie /connect und opencode.json zusammenwirken

Bei OpenCode werden Credential und Provider-Einstellungen getrennt gespeichert.

• /connect speichert den API Key in ~/.local/share/opencode/auth.json.
• Das globale ~/.config/opencode/opencode.json definiert Provider und Modelle für den Benutzer.
• Ein opencode.json im Projektstamm ändert Einstellungen nur für dieses Projekt.

Konfigurationsdateien werden zusammengeführt. Bei einem Konflikt überschreibt eine spätere Quelle eine frühere. Für die gewöhnliche lokale Konfiguration ist diese Reihenfolge wichtig: globale Konfiguration → Datei aus OPENCODE_CONFIG → Projekt-opencode.json. Von einer Organisation verwaltete Einstellungen haben eine eigene höchste Priorität.

1. API Key über /connect speichern

Starten Sie OpenCode im Testverzeichnis:

mkdir opencode-first-test
cd opencode-first-test
opencode

Führen Sie in der TUI aus:

/connect

Wählen Sie Other, geben Sie als Provider-ID bettertoken ein und fügen Sie Ihren API Key in das Credential-Feld ein. Legen Sie den echten Key nicht im Prompt, in opencode.json, einem Screenshot oder Git ab.

Beenden Sie OpenCode nach dem Speichern und prüfen Sie, ob der Provider registriert wurde:

opencode auth list

Der Befehl soll den Provider anzeigen, ohne den Key selbst offenzulegen.

2. BetterToken als Provider hinzufügen

Für die Konfiguration in allen Projekten erstellen oder aktualisieren Sie:

~/.config/opencode/opencode.json

Wird der Provider nur in einem Repository benötigt, legen Sie opencode.json in dessen Stammverzeichnis ab. Die Minimalkonfiguration lautet:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/YOUR_MODEL_ID",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID"
        }
      }
    }
  }
}

Ersetzen Sie YOUR_MODEL_ID durch die genaue ID aus dem aktuellen BetterToken-Katalog. Derselbe Wert muss in model, als Schlüssel von models und in dessen name stehen. Ergänzen Sie die Base URL nicht um /chat/completions: OpenCode und @ai-sdk/openai-compatible bilden die Anfrage selbst.

Detaillierte Befehle für die automatische Einrichtung und aktuelle Einschränkungen von Modellgruppen stehen in der BetterToken-Dokumentation für OpenCode. Die Model ID bleibt in diesem Artikel ein Platzhalter, da sich die Liste verfügbarer Modelle ändert.

3. Prüfen, welche Datei Vorrang hat

Ein Projekt-opencode.json kann das globale Modell oder den Provider überschreiben. Wählt OpenCode einen unerwarteten Endpoint, prüfen Sie diese Quellen in Reihenfolge:

1. ~/.config/opencode/opencode.json;
2. den Wert von OPENCODE_CONFIG, falls die Variable gesetzt ist;
3. opencode.json im aktuellen Projekt oder im nächstgelegenen Elternverzeichnis bis zum Git-Stamm.

Löschen Sie Dateien nicht auf Verdacht. Vergleichen Sie in allen gefundenen Konfigurationen die Felder model, provider.bettertoken.options.baseURL und provider.bettertoken.models.

Die erste Anfrage ausführen und prüfen

Starten Sie OpenCode nach einer JSON-Änderung neu:

opencode

Öffnen Sie die Modellauswahl mit:

/models

Wählen Sie bettertoken/YOUR_MODEL_ID. Senden Sie danach eine kurze, leicht überprüfbare Anfrage:

Gib nur JSON zurück: {"tool":"opencode","sum":4}. Ändere keine Dateien.

Die erste Anfrage gilt als bestätigt, wenn alle vier Prüfungen übereinstimmen:

• OpenCode gibt gültiges JSON zurück und verändert keine Dateien;
• in der TUI ist bettertoken/YOUR_MODEL_ID ausgewählt;
• im BetterToken Dashboard erscheint eine Anfrage mit erwartetem Modell und Status;
• das Dashboard zeigt Input-, Output- und gegebenenfalls Cache-Token sowie die zugehörige Belastung.

Das Dashboard muss nicht als Ablage für den vollständigen Prompt oder die gesamte Antwort dienen: Gemeint sind Metadaten zu Token-Nutzung und Verbrauch. Fehlt der Eintrag, kann die Antwort wegen eines Konfigurations-Overrides von einem anderen Provider stammen.

Häufige Fehler beheben

opencode: command not found

Schließen und öffnen Sie das Terminal erneut. Prüfen Sie bei einer npm-Installation, ob das globale npm-Verzeichnis in PATH liegt. Starten Sie keinen zweiten Installer, bevor Sie geklärt haben, wo die erste Binärdatei installiert wurde.

401 oder Credential-Fehler

Führen Sie /connect erneut aus und wählen Sie die Provider-ID bettertoken. Prüfen Sie das Ergebnis mit opencode auth list. Fügen Sie den Key nicht zur schnellen Prüfung in die Kommandozeile oder JSON ein.

404 oder API-Fehler

provider.bettertoken.options.baseURL muss diese Base URL enthalten:

https://www.bettertoken.ai/v1

Fügen Sie /chat/completions nicht hinzu. Ist die URL korrekt, starten Sie OpenCode neu und wiederholen Sie die kurze Anfrage.

model not found

Vergleichen Sie die genaue Model ID mit der aktuellen Dokumentation und dem Modellkatalog. Das oberste Feld model muss bettertoken/YOUR_MODEL_ID lauten, und provider.bettertoken.models muss einen Schlüssel mit derselben YOUR_MODEL_ID enthalten.

OpenCode verwendet ein anderes Modell oder einen anderen Endpoint

Dies deutet meist auf einen Konfigurations-Override hin. Vergleichen Sie globale Datei, OPENCODE_CONFIG und Projektdatei. Die Projekteinstellung hat unter den Standarddateien die höhere Priorität. Starten Sie OpenCode nach einer Korrektur vollständig neu und prüfen Sie /models und das Dashboard erneut.

FAQ

Muss der API Key in opencode.json gespeichert werden?

Nein. Verwenden Sie für die normale Einrichtung /connect: OpenCode speichert das Credential in ~/.local/share/opencode/auth.json. Die Konfigurationsdatei kann ohne echten Key bleiben.

Welche Base URL braucht OpenCode?

Für den OpenAI-kompatiblen Provider BetterToken wird https://www.bettertoken.ai/v1 verwendet. Dies ist eine Base URL; /chat/completions wird nicht manuell ergänzt.

Globales oder Projekt-opencode.json wählen?

Die globale Datei eignet sich für einen gemeinsamen Provider und ein gemeinsames Modell. Eine Projektdatei ist passend, wenn das Repository eine andere Model ID oder andere Berechtigungen benötigt. Bei einem Konflikt überschreibt die Projektdatei die globale Datei.

Brauche ich ein OpenCode-Konto für den BetterToken-Provider?

Ein Custom Provider verwendet das Credential des gewählten API-Dienstes. BetterToken stellt den eigenen API Key bereit, ersetzt aber weder die OpenCode-Website noch ein Konto oder andere OpenCode-Dienste. Die aktuellen Anforderungen des Tools selbst stehen in der offiziellen OpenCode-Dokumentation.