OpenCode mit dem Uni-OpenWebUI verbinden

Vier Schritte, etwa 15 Minuten. Danach läuft OpenCode in jedem Projekt mit dem Uni-Modell – eingerichtet wird einmal, nicht pro Ordner.

Sie brauchen dafür: einen Terminal-Befehl, die beigelegte Datei opencode.json und Ihren Uni-Schlüssel. Kein Skript, kein verstecktes Verzeichnis, kein Formular in der App – und am Ende funktioniert derselbe Befehl in jedem Ordner.

Kurzfassung

Warum nicht die Desktop-App?

Die Desktop-App ist die komfortable Oberfläche – aber sie legt keinen Terminal-Befehl an (das Menü „Install CLI…“ existiert nur unter macOS). Wer nach der Desktop-Installation opencode im Terminal eintippt, bekommt „Befehl nicht gefunden“. Da der Terminal-Weg der eigentliche Arbeitsmodus ist (dort sieht man den Agenten Dateien lesen und Befehle ausführen), richten wir die Terminal-Version direkt ein. Die Desktop-App lässt sich danach optional dazunehmen – sie zeigt dieselben Sitzungen an.

Schritt 0: Einmal Terms und Fenster verstehen (3 Minuten)

Für alles Weitere brauchen Sie ein Terminal – ein Fenster, in dem man dem Computer Befehle als Text schreibt. Kein Chatt, keine Suchleiste: Sie tippen eine Zeile, drücken Enter, der Computer antwortet mit Text. So arbeitet der Agent später sichtbar, deshalb lohnt sich der kleine Einstieg.

Ein Terminal öffnen:

Der Unterschied zu Word & Co: Es gibt nichts zu klicken. Der Cursor blinkt hinter einem C:\Users\IhrName> (Windows) oder ihrname@rechner ~ % (macOS) und wartet auf eine Zeile Text. Genau dorthin tippen Sie im Folgenden.

Der Unterschied zum Chat: Sie schreiben dem Betriebssystem, nicht einem Modell. node --version ist keine Frage an eine KI, sondern ein Befehl ans System.

Schritt 1: Erreichbarkeit prüfen (1 Minute)

Im Browser https://openwebui.uni-freiburg.de öffnen.

Die Instanz ist nur aus dem Uni-Netz erreichbar. eduroam allein genügt nicht. VPN: FortiClient von rz.uni-freiburg.de (Services → Netz & Telefon → VPN), SSL-VPN mit Server fortivpn.uni-freiburg.de, Benutzername <Uniaccount>@uni-freiburg.de, Passwort = eduroam-Passwort.

Schritt 2: Schlüssel holen (2 Minuten)

1. In OpenWebUI unten links auf das Profil-Symbol klicken.
2. Einstellungen → Konto öffnen.
3. Zum Abschnitt API-Schlüssel scrollen, neben Zugangsdaten auf Anzeigen klicken (der Abschnitt ist eingeklappt).
4. Neuen Geheimschlüssel erstellen, dann API-Schlüssel kopieren.

Genau ein Key pro Konto. Ein zweiter Klick auf „Neuen Geheimschlüssel erstellen“ macht den ersten ungültig – alles, was ihn benutzt, wird abgewiesen. Der Key lässt sich jederzeit wieder anzeigen; er muss nicht erneuert werden.

Schritt 3: OpenCode installieren (10 Minuten, meist weniger)

3a. Node.js installieren (falls nicht vorhanden):

1. nodejs.org im Browser öffnen – dort ist der große grüne Knopf „LTS“ (Long Term Support; die stabile Variante). Klicken, die Datei lädt herunter (Windows: .msi, macOS: .pkg).
2. Die heruntergeladene Datei doppelklicken und den Installer durchklicken – die Standard-Einstellungen genügen, nichts umstellen. Windows fragt evtl. nach Admin-Rechten: erlaubt, das ist das normale Installieren eines Programms.
3. Danach ein neues Terminalfenster öffnen (wichtig: ein bereits offenes Fenster kennt das frisch installierte Programm noch nicht) und prüfen:

node --version

Erscheint eine Versionsnummer (z. B. v22.x.x), ist alles bereit.

3b. OpenCode installieren – im Terminal:

npm install -g @opencode/cli

Danach prüfen – und zwar in einem beliebigen Ordner, der Befehl gilt maschinenweit:

opencode --version

Erscheint eine Versionsnummer, ist der Befehl überall verfügbar: in Dokumente, auf dem Schreibtisch, in jedem Projektordner. Das liegt am PATH – einer globalen Befehlsliste von Windows/macOS, in die npm den Befehl einträgt.

Schritt 4: Eine Datei in den Benutzerordner (2 Minuten)

Die Datei opencode.json können Sie direkt hier herunterladen: opencode.json – rechtsklicken und „Speichern unter" (nicht im Browser öffnen). Sie gehört in Ihren Benutzerordner – den Ordner, der aufgeht, wenn Sie den Dateimanager öffnen:

1. opencode.json dorthin kopieren.
2. Datei mit einem Texteditor öffnen (Windows: Editor; macOS: TextEdit, dort „Format → In reinen Text umwandeln“).
3. Den Schlüssel aus Schritt 2 einsetzen: den Platzhalter PASTE_YOUR_KEY_HERE ersetzen, Anführungszeichen drumherum stehen lassen.
4. Speichern.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openwebui/standard-coding-ufr",
  "provider": {
    "openwebui": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Uni Freiburg",
      "options": {
        "baseURL": "https://openwebui.uni-freiburg.de/api/v1",
        "apiKey": "PASTE_YOUR_KEY_HERE"
      },
      "models": {
        "standard-coding-ufr": { "name": "Coding" },
        "standard-chat-ufr":   { "name": "Chat" },
        "ufr/coding-complex":  { "name": "Coding Complex",
                                 "limit": { "context": 1048576, "output": 32000 } },
        "gemma-4-31b-llmlb":   { "name": "Gemma 4 31B" }
      }
    }
  }
}

Warum der Benutzerordner? OpenCode sucht die Datei vom Arbeitsordner aufwärts bis zum Benutzerordner. Eine Datei dort gilt deshalb für alle Projekte darunter – Dokumente, Schreibtisch, alles, ohne dass in einem Projekt etwas liegt. Und sie ist sichtbar: kein Verzeichnis, das man erst einblenden muss.

Nur ein Sonderfall: Arbeiten Sie in einem Projekt außerhalb Ihres Benutzerordners (externe Festplatte, Netzlaufwerk), kopieren Sie dieselbe Datei zusätzlich in diesen Projektordner. Mehr ist nicht zu tun.

Schritt 5: Testen (1 Minute)

Terminal öffnen, in irgendeinem Projektordner opencode starten und schreiben:

Sag in einem Satz Hallo und nenne dein Modell.

Das Modell „Uni Freiburg → Coding“ ist durch die Datei vorbelegt. Antwortet es, ist die Einrichtung fertig – in jedem Projekt, ohne weiteren Schritt.

Die Desktop-App (optional): Wer die grafische Oberfläche dazu will, lädt sie von opencode.ai/download. Sie liest dieselbe Konfiguration und zeigt dieselben Sitzungen – eine zweite Einrichtung ist nicht nötig.

Wenn etwas nicht klappt

Drei Dinge, die man wissen sollte

• Ein Schlüssel, zwei Werkzeuge. Derselbe Uni-Schlüssel funktioniert in Hermes und in OpenCode. Wer beide einrichtet, legt ihn zweimal ab, erzeugt aber keinen zweiten Schlüssel – ein neuer Schlüssel entwertet den alten in beiden Werkzeugen.
• Der Schlüssel steht im Klartext in der Datei. Das ist bei einer Datei in Ihrem Benutzerordner vertretbar: Sie liegt in keinem Git-Repository und in keinem Cloud-Ordner. Geben Sie die Datei nie weiter, ohne vorher den Schlüssel zu entfernen. Wenn ein Schlüssel abhandenkommt: neuen erzeugen, der alte ist sofort ungültig.
• Denk-Modelle. OpenCode trennt Denken und Antwort selbst; hier ist nichts zu tun. Nur bei eigenen Skripten braucht es ein großzügiges max_tokens.