OpenCode: Vanilla → Pro Setup-Guide

Eine fundierte, hype-freie Anleitung, um eine saubere OpenCode-Installation in eine professionelle Programmierumgebung zu verwandeln. Basierend auf Praktiker-Recherchen (Data Leads Future, DEV.to, Medium) und realen Tests. Zuletzt aktualisiert: 2026-07-29

1. Installation

OpenCode ist in Go geschrieben und wird als einzelne Binärdatei ausgeliefert. Es benötigt bun als Laufzeitabhängigkeit.

Installation mit einem Befehl

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

Falls das fehlschlägt

OpenCode setzt auf bun. Wenn deine Umgebung die automatische Installation blockiert:

npm install -g bun

Dann führe das Installationsskript erneut aus oder installiere manuell von opencode.ai.

Was du bekommst

• opencode CLI — Terminal-TUI (Bubble Tea, tastaturgesteuert)
• OpenCode Desktop — eigenständige grafische App (für den täglichen Gebrauch empfohlen)
• VS Code / Cursor / Zed-Erweiterungen — über den Extension-Marketplace

Desktop-App vs. TUI

Die Desktop-App ist für die tägliche Arbeit deutlich effizienter. Sie unterstützt nativ Workspaces (Git-Worktrees), was die TUI nicht kann. Das allein rechtfertigt die Installation.

Installiere trotzdem zuerst die CLI – einige Plugins und Setup-Tools prüfen während der Initialisierung, ob der OpenCode-Befehl verfügbar ist.

Installation überprüfen

opencode --version

Du solltest eine Versionsnummer sehen (aktuell: 1.15+).

2. Provider-Konfiguration (entscheidend)

Dies ist der häufigste Fehler. OpenCode unterstützt über 75 LLM-Provider, aber die Art der Konfiguration ist entscheidend.

❌ Der falsche Weg

Du siehst, dass dein Modell nicht in der Liste ist, also klickst du auf "Benutzerdefinierter Provider" und gibst ein: Modell-ID, Basis-URL, API-Schlüssel.

Warum das Probleme verursacht: OpenCode hat keine Informationen über die Kontextfenstergröße, Preise oder Fähigkeiten deines Modells. Funktionen wie automatische Komprimierung des Kontextes, Token-Budgetierung und intelligente Modellauswahl funktionieren nicht mehr.

✅ Der richtige Weg

1. Öffne OpenCode Desktop → Einstellungen → Provider
2. Scrolle zum unteren Ende der Liste
3. Klicke auf "Weitere Provider anzeigen"
4. Suche deinen tatsächlichen Provider (z.B. OpenRouter, Together, Fireworks oder ein Relay)
5. Gib den API-Schlüssel dieses Providers ein

Nach der Konfiguration erscheinen alle Modelle dieses Providers mit vollständigen Metadaten – Kontextgröße, Preise, alles. Die Kontextverwaltungs-Plugins funktionieren korrekt.

Die Provider-ID finden

Nach der Konfiguration über "Weitere Provider anzeigen" wird die Provider-ID nicht in der Benutzeroberfläche angezeigt. OpenCode speichert sie hier:

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

Öffne diese Datei. Darin findest du deine Provider-ID und deinen API-Schlüssel.

Verfügbare kostenlose Modelle

• Big Pickle – ein verstecktes Modell, kostenlos verfügbar
• DeepSeek V4 Flash – effizienzoptimiertes MoE (284B total, 13B aktiviert), starke Code-Fähigkeiten
• Nemotron 3 Super – NVIDIAs hybrides MoE (120B, 12B aktiviert)

Empfohlene kostenpflichtige Provider

3. Terminal- & Plattform-Setup

macOS / Linux

OpenCode erkennt $SHELL automatisch. Kein Handlungsbedarf.

Windows

OpenCode Desktop verwendet standardmäßig PowerShell. Zwei Probleme: Einige Umgebungen blockieren PowerShell, und nicht-englische Locales verursachen Zeichenkodierungsfehler. Lösung: Setze die SHELL-Umgebungsvariable oder verwende WSL / Git Bash.

4. AGENTS.md – Dein Langzeitgedächtnis

Das ist die mit Abstand wirkungsvollste Maßnahme, die du umsetzen kannst.

Was AGENTS.md bewirkt

Drei Dinge:

1. Projektdaten werden festgehalten. Ohne AGENTS.md scannt das LLM in jeder neuen Sitzung das gesamte Projekt von Grund auf.

2. Wahrscheinlichkeitsverteilungen werden eingegrenzt. LLMs generieren Antworten probabilistisch. AGENTS.md verschiebt die Verteilungen zu deinen Konventionen.

3. Abhängigkeitsfehler werden vermieden. Schreibe deine Tools in AGENTS.md.

AGENTS.md erstellen

Führe /init in OpenCode aus. Die KI analysiert dein Projekt und generiert eine Basisversion.

Was ein gutes AGENTS.md enthält

# Projektübersicht

Eva ist eine persönliche KI-Assistenten-Plattform. Monorepo mit:
- Python-Backend (FastAPI) in `/backend`
- React + TypeScript-Frontend in `/frontend`
- MCP-Server-Plugins in `/mcp-servers`

# Technologiestack

- Python 3.14+ mit async/await durchgängig
- React 19 + Tailwind CSS 4 für das UI
- Bun als JavaScript-Laufzeitumgebung

# Befehle

- `uv sync --prerelease=allow` – Python-Abhängigkeiten synchronisieren
- `bun install` – Frontend-Abhängigkeiten installieren
- `pytest` – Python-Tests ausführen

# Codierungskonventionen

- Typannotationen: immer `str | None` verwenden, niemals `Optional[str]`
- Importe: zuerst Standardbibliothek, dann Drittanbieter, dann lokale
- Async: `async def` für alle I/O-gebundenen Funktionen verwenden

# Architekturregeln

- Backend-Dienste kommunizieren über Nachrichtenaustausch, nicht durch direkte Importe
- MCP-Server sind eigenständige Prozesse, keine eingebetteten Module

5. Die zwei integrierten Agents: Plan vs. Build

Build-Agent (Standard)

Vollständiger Toolzugriff. Für klare, eindeutige Aufgaben. Nicht für komplexe oder mehrdeutige Aufgaben verwenden.

Plan-Agent

Schreibgeschützter Analysemodus. Stellt klärende Fragen. Erstellt einen Ausführungsplan.

Professioneller Workflow: Jede neue Anforderung → Plan-Agent → Plan-Datei → neue Sitzung → Build-Agent

6. Planungs-Workflow-Modus (v1.15+)

Aktivieren

export OPENCODE_EXPERIMENTAL_PLAN_MODE=true

Die 5 Phasen

7. Workspaces – Parallele Entwicklung

Die Desktop-App hat Workspaces, basierend auf Git-Worktrees. Rechtsklick auf das Projektsymbol → Workspace aktivieren.

8. Sitzungsdisziplin

Das Problem: Kontextverfall – LLMs haben Primats- und Aktualitätseffekt.

Die Regel: Starte nach jedem größeren Meilenstein eine neue Sitzung.

9. Benutzerdefinierte Befehle

Definiere benutzerdefinierte Slash-Befehle als .opencode/commands/<name>.md-Dateien mit Frontmatter und $ARGUMENTS-Platzhalter.

10. Benutzerdefinierte Agents

• Global: ~/.config/opencode/agents/<name>.md
• Projekt: <Projekt>/.opencode/agents/<name>.md

11. Workflow für komplexe Projekte

Morgens: Synchronisieren & Planen → Ausführen: Build → Überprüfen: Den Kreis schließen

12. Kostenerwartungen

OpenCode Go: 10 $/Monat Abonnement.

13. Fortschrittspfad

Stufe 2: OpenSpec (SDD) → Stufe 3: Reflection → Stufe 4: Loop Engineering

Checkliste für den Schnellstart

• OpenCode CLI + Desktop installiert
• Provider über "Weitere Provider anzeigen" konfiguriert
• /init ausgeführt, um AGENTS.md zu erstellen
• OPENCODE_EXPERIMENTAL_PLAN_MODE=true aktiviert
• Mindestens einen benutzerdefinierten Agent erstellt