OpenCode unter Windows 11 einrichten

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:

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)

npm install -g opencode-ai

Variante B: Scoop

scoop install opencode

Variante C: Chocolatey (Admin-Terminal)

choco install opencode

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:

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/<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 (PowerShell, persistent für den Benutzer):

[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-DEIN-KEY", "User")

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): %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:

{
  "$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 → 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

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

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

10. Optional: OpenCode unter WSL

1. WSL installieren (PowerShell als Admin): wsl --install, danach Neustart
2. Im WSL-Terminal:

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

3. Windows-Dateien erreichst du unter /mnt/c/..., z. B.:

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

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

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)

# 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