OpenCode unter Ubuntu 24 LTS einrichten

1. Voraussetzungen

• Ubuntu 24 LTS
• Ein Terminal mit vernünftiger Darstellung – am besten das vorinstallierte GNOME Terminal oder eine Alternative wie Terminator.
• Für die Installation über npm: Node.js LTS (https://nodejs.org) – prüfen mit:

node --version
npm --version

Hinweis: Unter Ubuntu läuft OpenCode nativ in seiner idealen Umgebung. Der unter Windows empfohlene Umweg über WSL (Windows Subsystem for Linux) entfällt hier komplett, da alle Tools und Dateisystemzugriffe bereits auf Linux-Ebene stattfinden.

2. OpenRouter-Account und API-Key einrichten

OpenRouter ist ein Gateway: ein Account, ein API-Key, Zugriff auf fast alle relevanten Modelle – abgerechnet wird pro Token (Pay-as-you-go) gegen Guthaben.

1. Account erstellen: https://openrouter.ai
2. Guthaben aufladen: Settings → Credits (kleiner Betrag reicht zum Experimentieren, z. B. 10 €).
3. API-Key erstellen: https://openrouter.ai/settings/keys → Create API Key
4. Wichtig – Kosten deckeln: Beim Erstellen (oder nachträglich über Edit) kannst du dem Key ein Credit-Limit geben. Leg dafür einen dedizierten Key nur für OpenCode an (z. B. „opencode-ubuntu", Limit 20 €). Dann kann eine Agenten-Endlosschleife maximal dieses Budget verbrauchen.
5. Key kopieren (beginnt mit sk-or-...). Er wird nur einmal angezeigt.

Tipp: OpenRouter hat auch kostenlose Modelle – erkennbar am Suffix :free in der Modell-ID. Ideal zum Ausprobieren ohne Guthabenverbrauch, aber mit Rate-Limits. Die verfügbaren Modelle und IDs findest du unter https://openrouter.ai/models

3. OpenCode (Terminal-Version) installieren

Zwei gleichwertige Wege – einen davon wählen:

Variante A: npm (empfohlen, wenn Node.js vorhanden)

sudo npm install -g opencode-ai

Variante B: Offizielles Bash-Skript

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

Installation prüfen

Terminal neu starten (damit PATH greift), dann:

opencode --version

Falls opencode nicht gefunden wird: siehe Troubleshooting (Kapitel 13).

4. OpenRouter in OpenCode einbinden

1. In einen Projektordner wechseln (oder einen Testordner anlegen) und OpenCode starten:

mkdir -p ~/dev/mein-projekt
cd ~/dev/mein-projekt
opencode

2. In der TUI den Befehl eingeben:

/connect

3. In der Anbieterliste OpenRouter suchen und auswählen.
4. Den API-Key (sk-or-...) einfügen und mit Enter bestätigen.

Die Zugangsdaten werden lokal gespeichert unter:

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

5. Modell wählen:

/models

Viele OpenRouter-Modelle sind bereits vorgeladen. Die Modell-IDs folgen dem Schema openrouter/<anbieter>/<modell>, z. B.:

• openrouter/anthropic/claude-sonnet-4.5
• openrouter/openai/gpt-5
• openrouter/google/gemini-2.5-pro

Die exakten IDs ändern sich laufend – im Zweifel von https://openrouter.ai/models kopieren oder einfach im /models-Picker suchen.

Alternative: Umgebungsvariable statt /connect

Wer den Key nicht in auth.json speichern will, kann ihn als Umgebungsvariable setzen (Bash, persistent für den Benutzer):

echo 'export OPENROUTER_API_KEY="sk-or-DEIN-KEY"' >> ~/.bashrc
source ~/.bashrc

Danach Terminal neu starten.

5. Weitere Provider einbinden: Claude, ChatGPT & Co.

OpenCode kann mehrere Provider gleichzeitig verwalten. Jeder wird einmal per /connect eingerichtet; das aktive Modell wählst du jederzeit über /models. Alle Zugangsdaten landen in derselben auth.json.

Wichtige Begriffsklärung: Ein Claude- oder ChatGPT-Abo lässt sich nicht in OpenRouter einpflegen – OpenRouter rechnet immer über das eigene Guthaben ab, egal welche Abos du woanders hast. Wer ein bestehendes Abo oder einen API-Key eines Anbieters direkt nutzen will, bindet den jeweiligen Provider direkt in OpenCode ein – parallel zu OpenRouter. Beides existiert problemlos nebeneinander.

5.1 Anthropic (Claude)

1. /connect → Anthropic auswählen
2. Zwei Wege werden angeboten:
   • „Claude Pro/Max" → der Browser öffnet sich → mit dem Claude-Account anmelden (nutzt das bestehende Abo)
   • „Manually enter API Key" → API-Key von https://console.anthropic.com → Pay-per-Token, Abrechnung über Anthropic
3. /models → Claude-Modell wählen

Rechtlicher Hinweis (laut OpenCode-Doku): Anthropic untersagt die Nutzung des Claude-Abos außerhalb der eigenen Tools ausdrücklich; entsprechende Plugins wurden aus OpenCode entfernt (ab Version 1.3.0). Wer rechtlich auf Nummer sicher gehen will, nutzt den API-Key mit Pay-per-Token-Abrechnung.

Alternativ per Umgebungsvariable: ANTHROPIC_API_KEY

5.2 OpenAI (ChatGPT)

1. /connect → OpenAI auswählen
2. Zwei Wege werden angeboten:
   • „ChatGPT Plus/Pro" → Browser-Anmeldung → nutzt das bestehende ChatGPT-Abo (von OpenAI für solche Tools offiziell freigegeben)
   • „Manually enter API Key" → API-Key von https://platform.openai.com/api-keys → Pay-per-Token
3. /models → GPT-Modell wählen

Alternativ per Umgebungsvariable: OPENAI_API_KEY

5.3 GitHub Copilot

Falls ohnehin ein Copilot-Abo existiert:

1. /connect → GitHub Copilot auswählen
2. Die angezeigte URL https://github.com/login/device öffnen und den angezeigten Code eingeben
3. /models → Modell wählen (manche Modelle erfordern Copilot Pro+)

5.4 Wann welcher Weg?

Praxis-Tipp: Viele nutzen ein Abo als Standard (planbare Kosten) und OpenRouter als Ergänzung für alles, was das eigene Abo nicht abdeckt – z. B. das jeweils andere Frontier-Modell oder günstige offene Modelle wie DeepSeek, Kimi oder Qwen. Der Wechsel passiert zur Laufzeit per /models, IDs unterscheiden sich am Präfix: anthropic/... (direkt) vs. openrouter/anthropic/... (via OpenRouter).

6. Grundkonfiguration: opencode.json

OpenCode wird über eine Datei opencode.json konfiguriert:

• Projektweit: opencode.json im Projektroot (ins Git committen)
• Global (für alle Projekte): ~/.config/opencode/opencode.json

Beispiel: Standard-Modell festlegen und Modellauswahl eindampfen

Die OpenRouter-Modellliste ist riesig. Mit whitelist zeigst du im /models-Picker nur, was du wirklich nutzt:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openrouter/anthropic/claude-sonnet-4.5",
  "provider": {
    "openrouter": {
      "whitelist": [
        "anthropic/claude-sonnet-4.5",
        "openai/gpt-5",
        "google/gemini-2.5-pro"
      ]
    }
  }
}

(Das Gegenstück blacklist blendet gezielt einzelne Modelle aus.)

Beispiel: Provider-Routing steuern (OpenRouter-Spezialität)

OpenRouter leitet jede Anfrage an einen von mehreren Inference-Anbietern weiter. Du kannst festlegen, welcher genommen werden soll und ob Fallbacks erlaubt sind:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "moonshotai/kimi-k2": {
          "options": {
            "provider": {
              "order": ["baseten"],
              "allow_fallbacks": false
            }
          }
        }
      }
    }
  }
}

Beispiel: Modell manuell hinzufügen

Falls ein brandneues Modell im Picker noch fehlt:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "anbieter/neues-modell": {}
      }
    }
  }
}

7. OpenCode im VS-Code-Terminal nutzen

OpenCode hat eine offizielle VS-Code-Erweiterung, die sich automatisch installiert:

1. VS Code öffnen
2. Integriertes Terminal öffnen (Ctrl + `)
3. opencode ausführen → die Extension wird automatisch nachinstalliert

Falls die Auto-Installation nicht klappt: Im Extension Marketplace nach „OpenCode" suchen und manuell installieren.

Was die Integration kann

Zusätzlich teilt die Extension automatisch deine aktuelle Auswahl / den aktiven Tab als Kontext mit OpenCode.

Praktischer Workflow in VS Code

1. Projektordner in VS Code öffnen
2. Ctrl+Esc → OpenCode-Terminal öffnet sich
3. Code markieren → Frage stellen („Was macht diese Funktion?", „Finde den Bug hier")
4. Mit @ im Prompt lassen sich Dateien fuzzy-suchen und als Kontext anhängen

8. OpenCode Desktop (grafische App)

1. Installer laden: https://opencode.ai/download → Linux (.deb oder AppImage)
2. Paket installieren (z. B. sudo dpkg -i opencode.deb) oder AppImage ausführbar machen (chmod +x)
3. App starten

Die Desktop-App verwaltet Sessions mit Tabs und nutzt bei nativer Installation auf demselben Rechner dieselbe Konfiguration und dieselben Zugangsdaten wie die CLI (~/.local/share/opencode/ bzw. ~/.config/opencode/) – der OpenRouter-Key muss also nicht erneut eingetragen werden.

Tipp für Remote-Entwickler: Wer den OpenCode-Server auf einem Remote-System (z. B. VPS) betreibt (siehe Kapitel 10), verbindet die Desktop-App damit so: Auf dem Server opencode serve --hostname 0.0.0.0 --port 4096 starten und die App auf http://<server-ip>:4096 zeigen lassen. Achtung: bei --hostname 0.0.0.0 unbedingt ein Passwort setzen: OPENCODE_SERVER_PASSWORD=dein-passwort opencode serve --hostname 0.0.0.0.

9. Erste Schritte in einem Projekt

Projekt initialisieren

Im Projektroot OpenCode starten und ausführen:

/init

Das analysiert das Projekt und erzeugt eine AGENTS.md – die Projekt-Gedächtnisdatei (Build-/Test-Kommandos, Konventionen, Struktur). Diese Datei ins Git committen; sie macht jede weitere Session besser.

Plan-Modus vs. Build-Modus

Mit der Tab-Taste wechselst du zwischen:

• Plan: OpenCode darf nichts verändern, sondern schlägt nur vor, wie es etwas umsetzen würde. Ideal bei größeren Features: erst planen, Feedback geben, dann freigeben.
• Build: OpenCode ändert Dateien und führt Befehle aus.

Nützliche TUI-Befehle

Und für schnelle One-Shots ohne TUI (Skripte, Pipes):

opencode run "Erkläre die Datei src/index.ts"

10. Optional: OpenCode auf einem Headless-Server (z. B. VPS) betreiben

Da Ubuntu 24 LTS oft auf Servern ohne grafische Oberfläche zum Einsatz kommt, eignet es sich hervorragend als Backend für OpenCode.

1. Per SSH auf den Server verbinden und per Skript installieren:

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

2. Damit du von deinem lokalen Rechner aus darauf zugreifen kannst, startest du den Dienst wie folgt:

OPENCODE_SERVER_PASSWORD=dein-sicheres-passwort opencode serve --hostname 0.0.0.0 --port 4096

Wichtig: Du kannst dich nun mit der Desktop-App (oder der VS-Code-Extension via Remote-SSH) dorthin verbinden. Konfigurationsdateien und Repositories liegen dabei direkt auf dem entfernten Ubuntu-Dateisystem unter ~/.config/opencode/ und ~/.

11. Für Claude-Code-Umsteiger: das Mapping

Besonders relevant: OpenCode liest bestehende Claude-Code-Konventionen als Fallback automatisch mit:

• CLAUDE.md im Projekt (wenn keine AGENTS.md existiert)
• ~/.claude/CLAUDE.md global (wenn keine ~/.config/opencode/AGENTS.md existiert)
• ~/.claude/skills/ (Agent Skills)

Bestehende Projekte funktionieren also sofort weiter; auf Dauer lohnt die Migration zu AGENTS.md (offener Standard, tool-übergreifend).

12. Kostenkontrolle & gute Praktiken

• Key-Limit bei OpenRouter setzen (siehe Kapitel 2) – die wirksamste Bremse.
• Verbrauch beobachten: https://openrouter.ai/activity
• Teure vs. günstige Modelle bewusst einsetzen: Frontier-Modelle (Claude, GPT) für komplexe Aufgaben, günstige/offene Modelle (DeepSeek, Kimi, Qwen) für Routine. Wechsel jederzeit mit /models.
• :free-Modelle zum Experimentieren.
• AGENTS.md pflegen: Je besser die Projektanweisungen, desto weniger Tokens verschwendet der Agent mit Orientierung.
• Den Agenten nicht unbeaufsichtigt mit destruktiven Rechten auf produktiven Maschinen laufen lassen – Plan-Modus (Tab) nutzen, Änderungen per Git-Diff prüfen, bei Bedarf /undo.

13. Troubleshooting

opencode wird nicht erkannt (npm-Installation)

Terminal neu starten. Prüfen, wo npm globale Pakete ablegt:

npm prefix -g

Stelle sicher, dass dieser Pfad in deiner ~/.bashrc exportiert wird (z. B. export PATH=$PATH:$(npm prefix -g)/bin).

Darstellung in der TUI kaputt (Artefakte, flackernde Zeichen)

Prüfe die Einstellungen deines Terminal-Emulators (z. B. GNOME Terminal) und stelle sicher, dass eine Schriftart mit guter Unicode/Nerd-Font-Unterstützung genutzt wird.

VS-Code-Extension installiert sich nicht automatisch

• Sicherstellen, dass opencode wirklich im integrierten Terminal läuft
• Prüfen, ob der code-Befehl im PATH ist; falls nicht: in VS Code Ctrl+Shift+P → „Shell Command: Install 'code' command in PATH"
• Notfalls manuell aus dem Marketplace installieren

Modell antwortet mit Fehler / „no endpoints found"

• Guthaben bei OpenRouter prüfen
• Modell-ID exakt von https://openrouter.ai/models kopieren
• Manche Modelle erfordern im OpenRouter-Account das Akzeptieren von Anbieter-Bedingungen oder deaktiviertes Training-Opt-out (Settings → Privacy)

Woran erkenne ich, welcher Key/Provider aktiv ist?

Gespeicherte Provider liegen in ~/.local/share/opencode/auth.json; erneutes /connect überschreibt den Eintrag.

Kurzfassung (TL;DR)

# 1. Installieren
sudo npm install -g opencode-ai

# 2. Starten
cd ~/dev/mein-projekt
opencode

# 3. In der TUI:
/connect      # → OpenRouter → API-Key (sk-or-...) einfügen
/models       # → Modell wählen
/init         # → AGENTS.md erzeugen

Desktop-App zusätzlich: https://opencode.ai/download (Linux .deb/AppImage). VS-Code-Integration: einfach opencode im integrierten Terminal starten – die Extension installiert sich selbst. Weitere Provider (Claude-/ChatGPT-Abo, GitHub Copilot, API-Keys einzelner Anbieter): ebenfalls per /connect einbinden – siehe Kapitel 5. Kostenbremse: dedizierter OpenRouter-Key mit Credit-Limit.

Links: Dokumentation https://opencode.ai/docs · OpenRouter https://openrouter.ai · Modell-IDs https://openrouter.ai/models · GitHub https://github.com/anomalyco/opencode