OpenCode installieren und mit OmniProxy konfigurieren

OpenCode ist ein quelloffener Coding-Assistent, mit dem du im Terminal, in der IDE oder in der Desktop-Anwendung Code schreiben kannst. Dein Code und Kontext werden nicht gespeichert, weshalb sich OpenCode für Projekte mit hohen Datenschutzanforderungen eignet. build dient zum Ändern des Projekts. plan ist standardmäßig schreibgeschützt und eignet sich dazu, zunächst unbekannten Code zu verstehen und geplante Änderungen zu strukturieren. Den Modelldienst kannst du nach Bedarf auswählen.

Vorbereitung der Installation

Am einfachsten ist die Installation über das Installationsskript. Du benötigst ein modernes Terminal, in dem du Befehle ausführen und mit Projektdateien arbeiten kannst, beispielsweise WezTerm, Alacritty, Ghostty oder Kitty. Unter Windows solltest du vorzugsweise WSL verwenden. Damit lässt sich eine Linux-Umgebung unter Windows ausführen, die vollständigere Funktionen und eine bessere Leistung bietet.

Am einfachsten

Installationsskript

• curl opencode.ai/install
• Unter macOS Linux direkt verwenden
• Unter Windows wird WSL empfohlen

macOS Linux

Homebrew tap

• anomalyco/tap/opencode
• Wird häufiger aktualisiert als die Formel
• Auch für Arch ist ein Paket verfügbar

Natives Windows

Paketmanager

• choco oder scoop
• Oder global mit npm installieren
• Alternativ aus Releases herunterladen

Halte außerdem die Modell-ID aus der aktuellen Modellliste bereit. Mit der Modell-ID identifiziert der Dienst ein bestimmtes Modell eindeutig.

Installieren und zum ersten Mal starten

Der einfachste Installationsbefehl lautet:

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

Alternativ kannst du eine der folgenden Installationsmethoden verwenden:

• Node.js: npm install -g opencode-ai. Für Bun, pnpm und Yarn gibt es ebenfalls entsprechende Befehle zur globalen Installation. Weitere Informationen findest du auf der am Ende verlinkten Einführungsseite.
• Homebrew unter macOS und Linux: brew install anomalyco/tap/opencode. Verwende diesen Tap, da er häufiger aktualisiert wird als das vom Homebrew-Team gepflegte brew install opencode.
• Arch Linux: Für die stabile Version verwendest du sudo pacman -S opencode. Eine neuere Version ist über das AUR-Paket opencode-bin verfügbar.
• Windows: Verwende choco install opencode, scoop install opencode oder npm install -g opencode-ai. Binärdateien können außerdem über Releases heruntergeladen werden. Die Unterstützung für eine Installation mit Bun unter Windows befindet sich weiterhin in Entwicklung.

Wechsle in dein Projektverzeichnis und starte anschließend OpenCode:

cd /path/to/project
opencode

Bei der ersten Verwendung kannst du /init ausführen. Dadurch wird das Projekt analysiert und im Stammverzeichnis des Projekts eine Datei namens AGENTS.md erstellt. Diese Datei kann in Git eingecheckt werden, damit die darin enthaltenen Hinweise im Projekt erhalten bleiben.

Verbindungsparameter aus OmniProxy abrufen

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: Vollständige ID aus der aktuellen Modellliste von OmniProxy kopieren

baseURL ist die Dienstadresse, API Key sind die Zugangsdaten und Model ID ist der vollständige Name des Modells.

Für Anfragen über /v1/chat/completions wird das npm-Paket @ai-sdk/openai-compatible verwendet. Chat Completions ist eine Schnittstelle für Chat-Anfragen. Wechsle nur dann zu @ai-sdk/openai, wenn das Modell /v1/responses verwendet. Wenn OmniProxy über den Pfad für Chat Completions genutzt wird, behältst du das Kompatibilitätspaket bei.

Kopiere die Modell-ID vollständig aus der aktuellen Liste von OmniProxy und behalte dabei auch alle Schrägstriche bei. Zwei Referenz-IDs vom 2026-10-09 sind claude-sonnet-5-5 und gpt-6-luna. gpt-6-luna unterstützt Chat Completions. Funktionsaufrufe werden mit Chat Completions nur unterstützt, wenn reasoning_effort auf none gesetzt ist. Übernimm keine ID, die nicht in der Liste enthalten ist.

Tool-Konfiguration eintragen

Ein Provider ist eine Gruppe von Einstellungen, über die OpenCode eine Verbindung zu einem Modelldienst herstellt. Dienste, die mit OpenAI kompatibel sind, aber nicht in der Liste von /connect erscheinen, werden in der Provider-Dokumentation als benutzerdefinierte Provider bezeichnet. Ein OpenAI-kompatibler Dienst verwendet dasselbe Anfrageformat und kann daher von derselben Art von Client aufgerufen werden.

1. Führe in OpenCode /connect aus und scrolle zu Other.
2. Gib eine Provider-ID ein. Im folgenden Beispiel wird omniproxy verwendet. Wähle eine leicht zu merkende ID, da du in der Konfigurationsdatei dieselbe ID verwenden musst.
3. Gib den API Key von OmniProxy ein. In diesem Schritt werden nur die Zugangsdaten gespeichert. Adresse und Modelle müssen zusätzlich in opencode.json eingetragen werden. Die Zugangsdaten werden unter ~/.local/share/opencode/auth.json gespeichert.
4. Erstelle oder bearbeite im Projektverzeichnis die Datei opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniproxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniProxy",
      "options": {
        "baseURL": "https://your-omniproxy-origin.example/v1"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "gpt-6-luna": { "name": "GPT-6 Luna" }
      }
    }
  }
}

5. Führe /models aus. Der benutzerdefinierte Provider und seine Modelle werden in der Liste angezeigt.

Die unter /connect angegebene ID muss mit dem Schlüssel in opencode.json übereinstimmen. Schreibe den echten Schlüssel nicht in diese Datei. Wenn du /connect nicht verwendest, kannst du unter options.apiKey stattdessen eine Umgebungsvariable angeben, beispielsweise {env:VARIABLENNAME}. In einem Test am 2026-10-09 mit OpenCode 1.18.34 konnte die Verbindung auch hergestellt werden, indem der Schlüssel direkt unter options.apiKey im Projekt eingetragen wurde, ohne /connect zu verwenden. Wenn das Gateway den Schlüssel nicht überprüft, kann dieser Eintrag aus einer Platzhalterzeichenfolge bestehen, die nur lokal verwendet wird. Verwende für die Schlüssel unter models jeweils die vollständige ID aus der Liste.

Schlüssel

/connect

• Ganz unten Other auswählen
• Provider ID selbst festlegen
• Wird in auth.json gespeichert

Projekt

opencode.json

• provider-Schlüssel muss gleich heißen
• Für npm ein kompatibles Paket verwenden
• baseURL endet mit /v1

Auswahl

/models

• Modell erscheint in der Liste
• Vor der Frage eines auswählen
• ID muss der Gateway-Liste entsprechen

Mit einer echten Aufgabe überprüfen

Führe im Projektverzeichnis zunächst eine echte Aufgabe aus. Eine Modellreferenz hat das Format Provider-ID/Modell-ID. Schrägstriche innerhalb der Modell-ID müssen beibehalten werden:

opencode run --model omniproxy/claude-sonnet-5-5 --auto "Erkläre, was eine von dir angegebene Datei macht, ohne die Datei zu ändern."

Mit --auto darf dieser Durchlauf Tools verwenden, beispielsweise zum Lesen von Dateien. In einem Test am 2026-10-09 mit OpenCode 1.18.34 wurde der Inhalt der angegebenen Datei gelesen. Der erste Durchlauf dauerte ungefähr zwei Minuten.

Für die interaktive Verwendung führst du opencode aus und wählst anschließend mit /models ein Modell aus. Mit @ kannst du nach Dateien suchen. Mit opencode auth list kannst du prüfen, welche Zugangsdaten über /connect gespeichert wurden. Kontrolliere anschließend in den Aufrufprotokollen von OmniProxy die Quelle und die Modell-ID.

Start

opencode lässt sich starten

• Zuerst mit cd zum Projekt wechseln
• auth list zeigt die ID an
• Konfigurationsdatei befindet sich im Projekt

Aufgabe

Code wurde gelesen

• Nach einer bestimmten Datei fragen
• Erklärung dazu prüfen
• Falls falsch, /undo verwenden

Protokoll

Im Gateway sichtbar

• Quelle ist OpenCode
• Modell-ID stimmt überein
• Schlüssel nicht committen

Häufige Fehler

• OmniProxy erscheint nicht unter /models: Prüfe, ob die ID aus /connect mit dem Schlüssel in opencode.json übereinstimmt, ob npm auf @ai-sdk/openai-compatible gesetzt ist und ob baseURL mit /v1 endet.
• Die Zugangsdaten fehlen: Führe opencode auth list aus. Provider wie Bedrock, die Umgebungsvariablen verwenden, erscheinen dort nicht. Ein über /connect eingerichteter benutzerdefinierter Provider sollte dagegen sichtbar sein.
• Unter Windows stehen nicht alle Funktionen zur Verfügung: Verwende das Installationsskript innerhalb von WSL.
• Die Modell-ID ist ungültig: Kopiere sie erneut aus der aktuellen Liste von OmniProxy und passe den entsprechenden Schlüssel unter models an.
• Die Anfrage verwendet die falsche Schnittstelle: Behalte für Chat Completions @ai-sdk/openai-compatible bei. Wechsle nicht wegen der Responses-Schnittstelle das Paket, außer das betreffende Modell verwendet bei OmniProxy tatsächlich /v1/responses.

Offizielle Referenzen

Informationen zur Installation findest du unter OpenCode Einführung. Benutzerdefinierte Provider werden unter Providers beschrieben. Informationen zu den als Beispiele verwendeten Modell-IDs findest du in der Claude-Modellübersicht und unter GPT-6 Luna.

Ersetze jeden Platzhalter durch Werte aus deiner OmniProxy-Konfiguration. Veröffentliche niemals einen echten Schlüssel.

Ein gespeichertes Ergebnis oder HTTP 200 allein beweist keine vollständige Agenten-Kompatibilität. Prüfe Quelle und Modell im OmniProxy-Aufrufprotokoll.

Offizielle Quellen · OpenCode ↗