# OpenCode unter Windows 11 einrichten (Terminal, VS Code, Desktop) + OpenRouter-Anbindung **Zielgruppe:** Umsteiger von Claude Code CLI / Einsteiger in OpenCode **Plattform:** Windows 11 **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 - Windows 11 - Ein Terminal mit vernünftiger Darstellung – am besten **Windows Terminal** (vorinstalliert bzw. über den Microsoft Store). Die klassische `cmd.exe`-Konsole verursacht Darstellungsprobleme in der TUI. - Für die Installation über npm: **Node.js LTS** (https://nodejs.org) – prüfen mit: ```powershell node --version npm --version ``` > **Hinweis WSL:** Das OpenCode-Team empfiehlt offiziell die Nutzung unter **WSL** (Windows Subsystem for Linux), weil Performance und Tool-Kompatibilität dort am besten sind. Die native Windows-Installation funktioniert aber und ist für den Einstieg völlig ausreichend. WSL ist in Kapitel 10 als optionaler Pfad beschrieben. --- ## 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-windows", 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 Drei gleichwertige Wege – **einen** davon wählen: ### Variante A: npm (empfohlen, wenn Node.js vorhanden) ```powershell npm install -g opencode-ai ``` ### Variante B: Scoop ```powershell scoop install opencode ``` ### Variante C: Chocolatey (Admin-Terminal) ```powershell choco install opencode ``` ### Installation prüfen Terminal **neu starten** (damit PATH greift), dann: ```powershell 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: ```powershell cd C:\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: ``` %USERPROFILE%\.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 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 (PowerShell, persistent für den Benutzer): ```powershell [Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-DEIN-KEY", "User") ``` 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 → 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? | 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** (Anthropic, OpenAI, …) | Pro Token, beim jeweiligen Anbieter | Nur 1–2 Modelle nötig, Abrechnung läuft ohnehin schon beim Anbieter, Enterprise-Vorgaben | | **Abo** (Claude Pro/Max, ChatGPT Plus/Pro, Copilot) | 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):** `%USERPROFILE%\.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 (Windows) | |---|---| | 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 → **Windows (x64)** 2. NSIS-Installer ausführen 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 (`%USERPROFILE%\.local\share\opencode\` bzw. `%USERPROFILE%\.config\opencode\`) – der OpenRouter-Key muss also **nicht** erneut eingetragen werden. > **Wer den Server unter WSL betreibt** (Kapitel 10), verbindet die Desktop-App damit so: in WSL `opencode serve --hostname 0.0.0.0 --port 4096` starten und die App auf `http://localhost: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): ```powershell opencode run "Erkläre die Datei src/index.ts" ``` --- ## 10. Optional: OpenCode unter WSL (empfohlener Weg für Heavy User) 1. WSL installieren (PowerShell als Admin): `wsl --install`, danach Neustart 2. Im WSL-Terminal: ```bash curl -fsSL https://opencode.ai/install | bash ``` 3. Windows-Dateien erreichst du unter `/mnt/c/...`, z. B.: ```bash cd /mnt/c/dev/mein-projekt opencode ``` **Wichtig:** WSL ist eine eigene Umgebung – Config und `auth.json` liegen dort unter `~/.config/opencode/` bzw. `~/.local/share/opencode/`, der `/connect`-Schritt muss also einmal in WSL wiederholt werden. Für maximale Performance Repos direkt ins WSL-Dateisystem klonen (`~/code/`) statt über `/mnt/c` zu arbeiten. Kombination mit VS Code: die Erweiterung **„WSL"** (Remote Development) nutzen. --- ## 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) | | 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 - **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: ```powershell npm prefix -g ``` Dieser Pfad muss in der `PATH`-Umgebungsvariable des Benutzers stehen. **Darstellung in der TUI kaputt (Artefakte, flackernde Zeichen)** Windows Terminal statt der Legacy-Konsole verwenden; alternativ PowerShell 7 (https://github.com/PowerShell/PowerShell). **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 `%USERPROFILE%\.local\share\opencode\auth.json`; erneutes `/connect` überschreibt den Eintrag. --- ## Kurzfassung (TL;DR) ```powershell # 1. Installieren npm install -g opencode-ai # 2. Starten cd C:\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 (Windows x64). 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