OpenCode API Key: Astra, Grok und Proxy einrichten

Viele Fragen zur Authentifizierung in OpenCode klingen ähnlich, betreffen aber unterschiedliche Ebenen. Der API Key eines Modell-Providers ist nicht dasselbe wie eine OpenCode-Go-Anmeldung, ein xAI-OAuth-Ablauf oder das Passwort zum Schutz von opencode web.

Dieser Leitfaden trennt diese Ebenen und zeigt eine funktionierende Custom-Provider-Konfiguration für BetterToken. Enthalten sind ein direkt nutzbares Beispiel für gpt-6-astra, regionale Netzwerkeinstellungen für Linux und Astra Linux, die direkte Grok-Authentifizierung sowie die korrekte Absicherung der OpenCode-Weboberfläche.

OpenCode entwickelt sich schnell weiter. Gleiche die folgenden Befehle vor dem produktiven Einsatz mit der aktuellen OpenCode-Dokumentation ab und prüfe die genaue Modell-ID im BetterToken-Modellkatalog.

Schnellübersicht

Ziel	Richtiger Ort oder Befehl
API Key eines Providers interaktiv speichern	In OpenCode `/connect` ausführen
Gespeicherte Provider anzeigen	`opencode auth list` ausführen
Custom Provider, Base URL und Modelle definieren	`opencode.json` oder `opencode.jsonc`
BetterToken verwenden	Base URL: `https://www.bettertoken.ai/v1`
GPT-6 Astra verwenden	Modell-ID: `gpt-6-astra`, sofern für dein Konto verfügbar
Bei OpenCode Go anmelden	`/connect` → OpenCode Go → `https://opencode.ai/auth`
Direkt bei xAI/Grok authentifizieren	`/connect` → xAI → OAuth-Abonnement oder API Key
OpenCode Web schützen	Vor `opencode web` `OPENCODE_SERVER_PASSWORD` setzen
Regionalen oder Unternehmens-Proxy verwenden	`HTTP_PROXY`, `HTTPS_PROXY` und `NO_PROXY` setzen

Voraussetzungen

Bereite Folgendes vor:

eine aktuelle OpenCode-Installation;
einen separaten API Key für Tests statt eines gemeinsam verwendeten Produktionsschlüssels;
die genaue Modell-ID aus dem Provider-Katalog;
ein kleines Test-Repository, in dem der Agent keine wichtigen Dateien verändern kann;
Terminalzugriff auf den OpenCode-Installer und den API-Endpunkt.

Behandle einen API Key wie ein Passwort. Füge keinen echten Schlüssel in einen Prompt, Screenshot, ein Issue, einen Artikel oder ein Git-Repository ein.

OpenCode installieren

Der offizielle Installer funktioniert unter macOS und Linux:

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

Alternativ ist die Installation über npm möglich:

npm install -g opencode-ai

Unter Windows empfiehlt OpenCode WSL für die beste Kompatibilität. Chocolatey und Scoop sind ebenfalls dokumentierte Optionen:

choco install opencode

scoop install opencode

Prüfe die Installation:

opencode --version

Es sollte eine Versionsnummer ausgegeben werden. Meldet die Shell command not found, öffne das Terminal erneut und prüfe, ob das Installationsverzeichnis in PATH enthalten ist.

Die vier Authentifizierungsebenen verstehen

1. API Key des Providers

Dieser Schlüssel autorisiert Aufrufe an BetterToken, xAI, OpenAI oder einen anderen Modell-Provider. OpenCode kann ihn über /connect speichern oder aus einer Umgebungsvariable lesen, auf die die Konfigurationsdatei verweist.

2. OpenCode-Go- oder OpenCode-Zen-Authentifizierung

OpenCode Go und Zen sind von OpenCode betriebene Modelldienste. Der Ablauf öffnet https://opencode.ai/auth. Dort meldest du dich an, richtest bei Bedarf die Abrechnung ein, kopierst einen API Key und fügst ihn wieder in /connect ein.

Dieser Schlüssel hat nichts mit deinem BetterToken-Schlüssel zu tun.

3. xAI-/Grok-Authentifizierung

Der aktuelle Provider-Ablauf von OpenCode unterstützt entweder ein berechtigtes xAI-Abonnement per Device-Code-OAuth oder einen nutzungsbasierten xAI API Key. Das ist eine direkte xAI-Verbindung und keine BetterToken-Verbindung.

4. OpenCode-Web-Passwort

OPENCODE_SERVER_PASSWORD schützt den lokalen OpenCode-HTTP-Server und die Browseroberfläche per Basic Auth. Es autorisiert keine Modellaufrufe und ersetzt keinen Provider-API-Key.

Einen API Key in OpenCode setzen

OpenCode unterstützt JSON und JSONC. Die offiziellen Beispiele verwenden häufig opencode.json; JSONC ist nützlich, wenn du Kommentare brauchst. Entscheidend ist, dass Zugangsdaten und Provider-Definition getrennt behandelt werden.

Methode 1: Schlüssel mit `/connect` speichern

Starte OpenCode in einem sicheren Testverzeichnis:

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

Führe in der TUI Folgendes aus:

/connect

Für BetterToken:

Wähle Other.
Gib als Provider-ID bettertoken ein.
Füge deinen BetterToken API Key in das Zugangsdatenfeld ein.
Beende oder starte OpenCode neu, nachdem du die Provider-Konfiguration hinzugefügt hast.

OpenCode speichert über /connect hinzugefügte Zugangsdaten hier:

~/.local/share/opencode/auth.json

Prüfe, ob der Provider registriert ist, ohne das Geheimnis auszugeben:

opencode auth list

Die in /connect verwendete Provider-ID muss exakt mit der ID in der Konfiguration übereinstimmen. Wenn du bettertoken eingegeben hast, muss der Konfigurationsschlüssel ebenfalls bettertoken lauten.

Methode 2: `opencode.json` oder `opencode.jsonc` konfigurieren

Verwende die globale Datei, wenn der Provider in jedem Projekt verfügbar sein soll:

~/.config/opencode/opencode.json

Verwende eine projektbezogene opencode.json oder opencode.jsonc, wenn nur ein Repository einen eigenen Modell- oder API-Endpunkt benötigt.

Das folgende Beispiel nutzt BetterToken und die aktuelle API-Modell-ID gpt-6-astra:

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

Prüfe vor der Verwendung, ob gpt-6-astra im aktuellen BetterToken-Katalog und in der Zugriffsgruppe deines Kontos erscheint. Zeigt der Katalog eine andere Modell-ID, ersetze sowohl bettertoken/gpt-6-astra als auch den Schlüssel gpt-6-astra unter models.

Hänge nicht /chat/completions an die Base URL an. Der Adapter baut den Anfragepfad selbst auf.

Umgebungsvariable statt `/connect` verwenden

Unter macOS oder Linux:

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

In PowerShell:

$env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"

Verweise anschließend in den Provider-Optionen auf die Variable:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/gpt-6-astra",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1",
        "apiKey": "{env:BETTERTOKEN_API_KEY}"
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        }
      }
    }
  }
}

Das ist sicherer, als das Geheimnis im Klartext in die JSON-Datei zu schreiben. Fehlt die Umgebungsvariable, ersetzt OpenCode sie durch eine leere Zeichenfolge, was normalerweise zu einem 401-Fehler führt.

Warum OpenCode deine Konfiguration ignorieren kann

OpenCode führt mehrere Konfigurationsquellen zusammen. Bei einem Konflikt desselben Feldes überschreiben spätere Quellen die früheren. Die wichtigsten Ebenen sind:

entfernte Standardwerte der Organisation;
globale Konfiguration in ~/.config/opencode/opencode.json;
eine über OPENCODE_CONFIG angegebene benutzerdefinierte Datei;
projektbezogene opencode.json oder opencode.jsonc;
Inline-Inhalt in OPENCODE_CONFIG_CONTENT;
administrativ verwaltete Einstellungen, die Benutzerdateien überschreiben können.

Wenn OpenCode das falsche Modell oder den falschen Endpunkt auswählt, lösche nicht wahllos Dateien. Suche alle aktiven Konfigurationen und vergleiche:

den Top-Level-Wert model;
provider.bettertoken.options.baseURL;
die Modellschlüssel unter provider.bettertoken.models;
OPENCODE_CONFIG und OPENCODE_CONFIG_CONTENT in der aktuellen Shell.

Starte OpenCode nach Änderungen an den Provider-Einstellungen neu.

OpenCode Astra: Modellname oder Astra Linux?

Die Suchanfrage „OpenCode Astra“ kann zwei verschiedene Dinge bedeuten.

GPT-6 Astra in OpenCode verwenden

Wenn du das OpenAI-Modell meinst, verwende die exakte API-ID gpt-6-astra. Mit dem obigen BetterToken-Provider wählst du:

bettertoken/gpt-6-astra

Öffne die Modellauswahl in OpenCode:

/models

Erscheint das Modell nicht, prüfe die Provider-ID, die models-Zuordnung, deine BetterToken-Zugriffsgruppe und den aktuellen Katalog. Leite eine Modell-ID nicht aus dem Anzeigenamen ab.

OpenCode unter Astra Linux ausführen

Die OpenCode-Dokumentation beschreibt Linux-Installationsmethoden, veröffentlicht aber keine eigene Zusage zur Unterstützung von Astra Linux. Behandle Astra Linux als Linux-Umgebung und prüfe die tatsächliche Maschine, statt Kompatibilität vorauszusetzen.

Prüfe Architektur und benötigte Werkzeuge:

uname -m
command -v curl
command -v bash

Teste anschließend Installer und API-Routen getrennt. Ein erreichbarer Modell-API-Endpunkt garantiert nicht, dass auch OpenCode-Installer, npm-Registry, GitHub oder Update-Server erreichbar sind.

Für einen Standard-Proxy:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,::1
opencode

NO_PROXY ist wichtig, weil die TUI mit einem lokalen OpenCode-HTTP-Server kommuniziert. Wird Loopback-Verkehr durch den Proxy geleitet, können Verbindungsschleifen entstehen oder die Oberfläche scheinbar einfrieren.

Wenn dein Unternehmen eine private Zertifizierungsstelle verwendet:

export NODE_EXTRA_CA_CERTS=/etc/company/ca.pem
opencode

Schreibe echte Proxy-Zugangsdaten nicht fest in gemeinsam genutzte Shell-Skripte. Nutze einen Secret Manager oder eine geschützte Umgebungskonfiguration deines Unternehmens.

OpenCode Grok Auth: direkte xAI-Verbindung oder Gateway?

Direkte Verbindung zu xAI

Führe Folgendes aus:

/connect

Wähle xAI. Die aktuelle OpenCode-Dokumentation nennt zwei Authentifizierungswege:

ein unterstütztes xAI-Abonnement per Device-Code-OAuth;
einen manuell aus der xAI-Konsole eingegebenen xAI API Key.

Führe nach der Autorisierung Folgendes aus:

/models

und wähle ein verfügbares Grok-Modell.

Grok über BetterToken oder ein anderes Gateway

Ein benutzerdefiniertes Gateway funktioniert nur, wenn es aktuell ein gültiges Grok-Modell und das passende Protokoll bereitstellt. Erfinde keine Grok-Modell-ID und gehe nicht davon aus, dass jedes OpenAI-kompatible Gateway xAI-Modelle anbietet.

Prüfe zuerst den Live-Katalog des Providers. Ist Grok nicht aufgeführt, verwende den direkten xAI-Provider von OpenCode. Community-Plugins wie Grok-Auth-Erweiterungen sind vom offiziellen Ablauf getrennt und sollten vor der Installation hinsichtlich Wartung, Berechtigungen und Umgang mit Zugangsdaten geprüft werden.

OpenCode Go Auth

OpenCode Go ist kein Befehl, der alle Provider authentifiziert. Es handelt sich um einen Abonnementdienst von OpenCode.

So stellst du die Verbindung her:

Führe /connect aus.
Wähle OpenCode Go.
Öffne https://opencode.ai/auth.
Melde dich an, schließe bei Bedarf die Abrechnungseinrichtung ab und kopiere den erzeugten Schlüssel.
Füge den Schlüssel wieder in OpenCode ein.
Führe /models aus und wähle ein Modell, das im Tarif enthalten ist.

Nutze diesen Ablauf nur, wenn du OpenCode Go verwenden möchtest. Für BetterToken bleiben Provider-ID und Schlüssel unter bettertoken.

OpenCode-Web-Passwort: Umgebungsvariable verwenden

opencode web password ist eine häufige Suchanfrage. Manche Beispiele empfehlen fälschlich einen Passwort-Parameter -p. Die dokumentierte Methode ist die Umgebungsvariable OPENCODE_SERVER_PASSWORD.

Unter macOS oder Linux:

OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' opencode web

Mit eigenem Benutzernamen:

OPENCODE_SERVER_USERNAME='developer' \
OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' \
opencode web

In PowerShell:

$env:OPENCODE_SERVER_USERNAME = "developer"
$env:OPENCODE_SERVER_PASSWORD = "replace-with-a-strong-password"
opencode web

Der Standardbenutzername ist opencode. Ohne Passwort kann eine rein lokale Nutzung auf 127.0.0.1 vertretbar sein, Netzwerkzugriff sollte jedoch geschützt werden. Binde den Dienst nicht an 0.0.0.0 und veröffentliche ihn nicht über einen Tunnel, bevor Authentifizierung und Netzwerkkontrollen eingerichtet sind.

Das Web-Passwort schützt den OpenCode-Server. Es schützt dein Provider-Konto nicht, wenn der Provider-Schlüssel an anderer Stelle offengelegt wurde.

Erste Anfrage prüfen

Starte OpenCode nach der JSON-Änderung neu:

opencode

Öffne die Modellauswahl:

/models

Wähle bettertoken/gpt-6-astra und sende einen kleinen, leicht prüfbaren Prompt:

Gib nur dieses JSON zurück und ändere keine Dateien: {"tool":"opencode","sum":4}

Eine erfolgreiche Einrichtung sollte alle folgenden Prüfungen erfüllen:

OpenCode liefert gültiges JSON zurück;
keine Projektdatei wird verändert;
das ausgewählte Modell ist bettertoken/gpt-6-astra;
im BetterToken-Dashboard erscheint eine passende Anfrage;
Modell, Status, Eingabe- und Ausgabetokens sowie Kosten wirken plausibel.

Antwortet OpenCode, aber bei BetterToken erscheint keine Anfrage, leitet möglicherweise eine höher priorisierte Konfiguration den Aufruf an einen anderen Provider weiter.

Fehlerbehebung

`401` oder Zugangsdatenfehler

Führe /connect erneut aus und verwende die Provider-ID bettertoken.
Führe opencode auth list aus.
Bei {env:BETTERTOKEN_API_KEY} prüfst du nur, ob die Variable vorhanden ist, ohne den geheimen Wert auszugeben.
Prüfe, ob der Schlüssel aktiv ist und ausreichendes Guthaben oder Berechtigungen besitzt.

`404` oder falscher API-Pfad

Die BetterToken-Base-URL lautet:

https://www.bettertoken.ai/v1

Hänge /chat/completions nicht manuell an.

`model not found`

Prüfe die exakte aktuelle ID im Modellkatalog. Der Top-Level-Wert model und der Schlüssel unter models müssen zum gewünschten Provider und Modell passen.

Falscher Endpunkt oder falsches Modell

Prüfe globale, benutzerdefinierte, projektbezogene, Inline- und verwaltete Konfigurationen. Starte OpenCode danach neu und wähle das Modell erneut über /models.

OpenCode hängt bei aktiviertem Proxy

Stelle sicher, dass Loopback-Adressen ausgeschlossen sind:

export NO_PROXY=localhost,127.0.0.1,::1

OpenCode Web antwortet mit `Unauthorized`

Prüfe, ob der Browser den konfigurierten Benutzernamen und das Passwort verwendet. Kontrolliere außerdem, ob in der Shell noch ein alter Wert von OPENCODE_SERVER_PASSWORD gesetzt ist oder ein Client-Prozess einen anderen Wert geerbt hat.

`opencode: command not found`

Öffne das Terminal erneut, prüfe PATH und führe den Befehl deines Paketmanagers aus, der das globale Binärverzeichnis anzeigt. Installiere dasselbe Programm nicht über mehrere Paketmanager, bevor klar ist, welche ausführbare Datei aktiv ist.

Häufig gestellte Fragen

Wie setze ich einen API Key in OpenCode?

Die empfohlene interaktive Methode ist /connect. Wähle bei einem Custom Provider Other, gib die Provider-ID ein und füge den Schlüssel ein. Den Provider und seine Modelle musst du zusätzlich in opencode.json oder opencode.jsonc definieren.

Heißt die Datei `opencode.json` oder `opencode.jsonc`?

OpenCode unterstützt JSON und JSONC. Verwende JSONC, wenn du Kommentare benötigst. Halte nur eine Projektkonfiguration aktiv, sofern du nicht bewusst mit der Zusammenführung mehrerer Quellen arbeitest.

Wo speichert OpenCode API Keys?

Über /connect hinzugefügte Zugangsdaten liegen in ~/.local/share/opencode/auth.json. Veröffentliche, synchronisiere oder commite diese Datei nicht.

Kann ich den API Key direkt in die Konfiguration schreiben?

OpenCode unterstützt options.apiKey, aber ein Klartext-Geheimnis in einer versionierten JSON-Datei ist riskant. Bevorzuge /connect, {env:VARIABLE_NAME} oder {file:path/to/secret}.

Ist OpenCode-Go-Auth dasselbe wie Provider-Auth?

Nein. OpenCode Go ist ein separater OpenCode-Dienst. Ein BetterToken-, xAI- oder anderer Provider-Schlüssel bleibt unabhängig davon.

Wie setze ich ein OpenCode-Web-Passwort?

Setze OPENCODE_SERVER_PASSWORD, bevor du opencode web ausführst. Die dokumentierte Methode ist eine Umgebungsvariable und kein allgemeiner Passwort-Parameter -p.

Wie authentifiziere ich Grok in OpenCode?

Führe /connect aus, wähle xAI und nutze entweder den unterstützten OAuth-Ablauf eines Abonnements oder die manuelle Eingabe eines xAI API Keys. Ein Gateway ist nur geeignet, wenn es tatsächlich ein Grok-Modell auflistet.

Bedeutet „OpenCode Astra“ GPT-6 Astra oder Astra Linux?

Beides ist möglich. Verwende für das Modell gpt-6-astra. Bei Astra Linux befolgst du die Linux-Installations- und Netzwerkprüfungen und validierst den konkreten Distributions-Build.

Benötige ich ein VPN, um OpenCode aus Russland zu verwenden?

Darauf gibt es keine pauschale Antwort, weil Installationsdownloads, GitHub, npm, die OpenCode-Website und die Modell-API getrennte Netzwerkpfade sind. Teste jeden Pfad einzeln und verwende bei Bedarf regelkonforme regionale oder Unternehmensnetzwerkeinstellungen.