Hier ist das für Ubuntu 24 LTS adaptierte Tutorial, das du direkt für deine Homepage verwenden kannst. Alle Windows-spezifischen Befehle, Pfade und Konzepte wurden durch die entsprechenden Linux-Äquivalente ersetzt. # OpenCode unter Linux (Ubuntu 24 LTS) einrichten (Terminal, VS Code, Desktop) + OpenRouter-Anbindung **Zielgruppe:** Umsteiger von Claude Code CLI / Einsteiger in OpenCode **Plattform:** Ubuntu 24 LTS **Ergebnis:** OpenCode ist als Terminal-App (TUI) und Desktop-App installiert, läuft im VS-Code-Terminal und nutzt OpenRouter als Modell-Backend (Zugriff auf 100+ Modelle von Anthropic, OpenAI, Google, DeepSeek, Moonshot, Qwen u.v.m. über **einen** API-Key). --- ## 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](https://nodejs.org)) – prüfen mit: ```bash 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](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](https://www.google.com/search?q=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](https://openrouter.ai/models) > > --- ## 3. OpenCode (Terminal-Version) installieren Zwei gleichwertige Wege – **einen** davon wählen: ### Variante A: npm (empfohlen, wenn Node.js vorhanden) ```bash sudo npm install -g opencode-ai ``` ### Variante B: Offizielles Bash-Skript ```bash curl -fsSL https://opencode.ai/install | bash ``` ### Installation prüfen Terminal **neu starten** (damit der PATH greift), dann: ```bash 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: ```bash 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//`, 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](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): ```bash echo 'export OPENROUTER_API_KEY="sk-or-DEIN-KEY"' >> ~/.bashrc source ~/.bashrc ``` Danach Terminal neu starten. --- ## 5. Weitere Provider einbinden: Claude, ChatGPT & Co. (Abos und API-Keys) 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](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](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](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? | Weg | Abrechnung | Wann sinnvoll | | --- | --- | --- | | **OpenRouter** | Pro Token, gegen OpenRouter-Guthaben | Ein Key für 100+ Modelle; ideal zum Vergleichen und als universeller Standard | | **Direkter API-Key** | Pro Token, beim jeweiligen Anbieter | Nur 1–2 Modelle nötig, Abrechnung läuft ohnehin schon beim Anbieter, Enterprise-Vorgaben | | **Abo** | Flatrate im bestehenden Abo | Abo ohnehin vorhanden, vorhersehbare Kosten; beschränkt auf die Modelle des Anbieters | **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: ```json { "$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: ```json { "$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: ```json { "$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 | Aktion | Tastenkürzel (Linux) | | --- | --- | | OpenCode in Split-Terminal öffnen / fokussieren | `Ctrl+Esc` | | Neue OpenCode-Session | `Ctrl+Shift+Esc` | | Datei-Referenz einfügen (z. B. `@File#L37-42`) | `Alt+Ctrl+K` | 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](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://: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 | Befehl | Wirkung | | --- | --- | | `/connect` | Provider/API-Key einrichten | | `/models` | Modell wechseln | | `/init` | `AGENTS.md` erzeugen/verbessern | | `/undo` / `/redo` | Letzte Änderung zurücknehmen / wiederholen (mehrfach möglich) | | `/share` | Konversation als Link teilen (opt-in, nichts wird automatisch geteilt) | | `/editor` / `/export` | Session im externen Editor öffnen / exportieren | Und für schnelle One-Shots ohne TUI (Skripte, Pipes): ```bash 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: ```bash curl -fsSL https://opencode.ai/install | bash ``` 2. Damit du von deinem lokalen Rechner aus darauf zugreifen kannst, startest du den Dienst wie folgt: ```bash 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 | Claude Code | OpenCode | | --- | --- | | `claude` starten | `opencode` starten | | `/login` | `/connect` | | `/model` | `/models` | | `CLAUDE.md` | `AGENTS.md` (per `/init` erzeugen) | | Plan-Modus mit `Shift+Tab` | **`Tab`** | | `/cost` | OpenRouter-Dashboard ([https://openrouter.ai/activity](https://www.google.com/search?q=https://openrouter.ai/activity)) | | Abo-Abrechnung (flat) | Wahlweise: Abo direkt einbinden (Kapitel 5) oder Pay-as-you-go über OpenRouter | **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](https://www.google.com/search?q=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: ```bash 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](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) ```bash # 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](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](https://opencode.ai/docs) · OpenRouter [https://openrouter.ai](https://openrouter.ai) · Modell-IDs [https://openrouter.ai/models](https://openrouter.ai/models) · GitHub [https://github.com/anomalyco/opencode](https://github.com/anomalyco/opencode)