OpenCode 2.0 Upgrade: v1-Konfiguration, Plugins und Sessions migrieren

Name

Soren Atelier

Aktualisiert am 4.11.2026

Kurz gesagt: Sichern Sie Ihre OpenCode-Ordner, aktualisieren Sie auf das neueste 1.x-Release und führen Sie dann das Major-Upgrade aus.

# 1. Config und Daten sichern (Sessions liegen im Datenordner)
cp -R ~/.config/opencode ~/opencode-v1-config-backup
cp -R ~/.local/share/opencode ~/opencode-v1-data-backup
 
# 2. Zuerst auf das neueste 1.x (--major gibt es ab v1.19.0)
opencode upgrade
 
# 3. Auf OpenCode 2 wechseln
opencode upgrade --major

In der Terminal-UI macht /update dasselbe. Wenn Sie lieber neu installieren, entfernen Sie zuerst das v1-Paket und nutzen dann einen der v2-Installationsbefehle aus Schritt 3.

Die meisten v1-Einstellungen funktionieren weiter. Drei Dinge brechen absichtlich: v1-Plugins laden nicht, die Server-API ist neu, und tui.json wird durch cli.json ersetzt. Zwei leisere Änderungen überraschen viele: v2 liest CLAUDE.md nicht mehr, und es erlaubt standardmäßig Zugriff auf Ordner außerhalb des Projekts. Dieser Guide behandelt jeden Punkt, dazu die bekannten Bugs aus den ersten Wochen von 2.x.

Was wir geprüft haben und was nicht: Am 25. Oktober 2026 haben wir die v1-Seite auf macOS mit installiertem OpenCode 1.18.19 geprüft. Wir haben die Befehle upgrade, export, session und debug paths gelesen. Außerdem haben wir die npm-Registry-Daten zu @opencode/cli 2.1.4 sowie die unten zitierten GitHub-Issues und Maintainer-Antworten gelesen. OpenCode 2 haben wir für diesen Guide nicht ausgeführt. Alle Aussagen zum Verhalten von v2 stammen aus dem offiziellen Migrationsleitfaden (opens in a new tab), den v2-Docs (opens in a new tab), der Ankündigung von OpenCode 2.0 (opens in a new tab) und diesen Maintainer-Antworten. Jede Quelle ist verlinkt. Am 4. November 2026 haben wir Versionen, Release-Seiten und Issue-Threads erneut gegen @opencode/cli 2.2.5 und opencode-ai 1.19.5 geprüft.

Sollten Sie jetzt upgraden?

OpenCode 2.0 erschien am 11. September 2026 auf npm als @opencode/cli. Viele v1-Nutzer, die über npm oder das Installationsskript installiert hatten, haben es erst im Oktober bemerkt (Nutzer von Homebrew core bekamen es früher, siehe die Homebrew-Falle in Schritt 3). Der Grund: Der Weg über opencode upgrade --major kam mit v1.19.0 am 11. Oktober, und das Team hat 2.0 am 14. Oktober angekündigt. Die Ankündigung erreichte 888 Punkte auf Hacker News. Seit dem 11. Oktober hat das Repo über 4.000 neue Issues bekommen, 130 davon erwähnen 2.0.

Beide Versionen werden jetzt parallel ausgeliefert. opencode-ai auf npm ist weiterhin v1 (1.19.5 am 28. Oktober). @opencode/cli ist v2 (2.2.5 am 30. Oktober). Seit v2.2.0 (27. Oktober) erscheinen 2.x-Builds auch auf GitHub Releases (opens in a new tab), aber das als Latest markierte Release ist weiterhin 1.x. Das ist Absicht: v1 sucht Updates über das Latest-Release, und das Team will nicht, dass das v1-Auto-Update Nutzer auf 2.x springen lässt (#57675 (opens in a new tab)).

Schritt 1: Backup, bevor Sie etwas anfassen

Der offizielle Migrationsleitfaden empfiehlt, während des Testens eine Kopie Ihres v1-Setups zu behalten. Was genau zu kopieren ist, sagt er nicht. Unter macOS und Linux listet opencode debug paths die Ordner auf. Unsere 1.18.19-Installation zeigte:

Kopieren Sie die ersten beiden (mit den Befehlen oben auf dieser Seite). Beenden Sie OpenCode vorher, damit die Session-Datenbank (opencode.db und ihre -wal-Datei) in einem konsistenten Zustand kopiert wird. Kopieren Sie auch alle projektbezogenen opencode.json-Dateien und .opencode/-Ordner, die Ihnen wichtig sind. Diese liegen in Ihren Repos, sind also meist ohnehin von git erfasst.

Um eine portable Kopie einer wichtigen Unterhaltung zu bekommen, exportieren Sie sie vor dem Upgrade aus v1:

opencode session list
opencode export <sessionID> > my-session.json

opencode export schreibt die Session als JSON. Mit --sanitize entfernen Sie sensible Transkript- und Dateidaten, bevor Sie die Datei teilen.

Schritt 2: Auf das neueste 1.x aktualisieren

opencode upgrade --major gibt es erst ab v1.19.0. Auf unserer 1.18.19-Installation zeigte opencode upgrade --help kein --major-Flag. Wenn Sie 1.18 oder älter nutzen, führen Sie zuerst ein normales Upgrade aus:

opencode --version
opencode upgrade

Prüfen Sie danach, dass opencode --version 1.19.x ausgibt. Seit v1.19.0 installieren sich Updates nicht mehr selbst. Eine alte Installation bleibt also alt, bis Sie diesen Befehl ausführen.

Schritt 3: Upgrade oder v2 neu installieren

In-place-Upgrade (ab 1.19.x):

opencode upgrade --major

Neuinstallation. Laut Migrationsleitfaden sollten Sie eine per Paketmanager installierte v1 zuerst entfernen, weil v1 und v2 standardmäßig nicht nebeneinander installiert werden. Wählen Sie dann einen der offiziellen v2-Befehle:

# Offizieller Installer (ersetzt das v1-Binary)
curl -fsSL https://opencode.ai/v2/install | bash
 
# Homebrew (beachten Sie die Formel mit -v2; eine v1-Installation per brew zuerst entfernen)
brew uninstall opencode
brew install anomalyco/tap/opencode-v2
 
# npm (neuer Paketname)
npm uninstall -g opencode-ai
npm install -g @opencode/cli

Fallen bei Paketmanagern:

• npm-Paketname. v1 heißt opencode-ai. v2 heißt @opencode/cli. Wer heute npm install -g opencode-ai ausführt, bekommt weiterhin 1.19.5.
• Homebrew core vs. Tap. brew install opencode (ohne Tap) installiert seit dem 28. September OpenCode 2, brew upgrade stellt eine solche Installation also bereits ohne --major auf 2.x um. Die 1.x-Formel ist anomalyco/tap/opencode, die 2.x-Formel anomalyco/tap/opencode-v2. Die beiden kollidieren, führen Sie also brew uninstall opencode aus, bevor Sie die jeweils andere installieren.
• Install-Skripte. Das v2-npm-Paket wählt das native Binary per postinstall-Skript aus. Mit Bun oder pnpm brauchen Sie --trust (Bun) bzw. --allow-build=@opencode/cli (pnpm). Ohne dieses Flag fehlt das Binary.
• Zwei Befehlsnamen. Das npm-Paket registriert in seinem bin-Feld sowohl opencode als auch opencode2 (wir haben die Registry-Metadaten geprüft).
• mise installiert v2 erst ab mise 2026.10.9. Ältere mise-Versionen installieren OpenCode 1.
• Windows-Paketmanager (Scoop, Chocolatey) werden für v2 nicht unterstützt, und opencode upgrade --major kann solche Installationen nicht umstellen. Laden Sie das eigenständige Windows-CLI-Binary oder die Desktop-App von der v2-Installationsseite (opens in a new tab) herunter, oder nutzen Sie WSL. Ein chinesischsprachiger Bericht über ein Hängenbleiben von v2 unter WSL (#55033 (opens in a new tab)) wurde am 16. Oktober wegen fehlender Details geschlossen.
• Docker: Versionierte Images gibt es, zum Beispiel ghcr.io/anomalyco/opencode:2.0.0.

Führen Sie opencode --version aus und prüfen Sie, dass 2.x ausgegeben wird.

Schritt 4: Prüfen, was v2 aus Ihrer v1-Config übernommen hat

Sie müssen Ihre Config nicht neu schreiben. v1 und v2 lesen dieselben Orte (~/.config/opencode/opencode.json, projektbezogene opencode.json, .opencode/). v2 bildet v1-Feldnamen im Speicher ab und schreibt Ihre Dateien nicht um. Beim ersten v2-Start wandern die globalen tui.json-Einstellungen in eine neue ~/.config/opencode/cli.json. Ihre v1-Dateien bleiben unverändert.

Öffnen Sie ein echtes Projekt und prüfen Sie fünf Dinge, bevor Sie dem Ergebnis vertrauen: Modelle, Provider-Zugangsdaten, Agents, Berechtigungen und MCP-Server. Der Migrationsleitfaden nutzt dieselbe Checkliste.

Falls Sie später auf native v2-Config umstellen wollen, sind das die wichtigsten Feldänderungen:

Zwei Regeln aus dem Leitfaden verhindern die meisten Migrationsfehler:

1. Jeden Eintrag in einem Format halten. Auf oberster Ebene dürfen Sie v1- und v2-Syntax mischen. Innerhalb eines einzelnen Agent-, Provider-, Command- oder Model-Eintrags entscheiden Sie sich für ein Format.
2. v1 nicht auf eine konvertierte Datei zeigen lassen. Beide Versionen lesen dieselben Pfade. Sobald Sie eine Datei auf reine v2-Syntax umstellen, kann v1 sie nicht mehr lesen. Wenn Sie einen Rollback einplanen, konvertieren Sie zuletzt.

Der Leitfaden schlägt außerdem vor, OpenCode die Konvertierung selbst erledigen zu lassen. Starten Sie v2 im Projekt und geben Sie diesen Prompt ein: "Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format. Preserve its behavior and all unrelated settings." (sinngemäß: Konfiguration inklusive dateibasierter Definitionen von v1 auf natives v2 umstellen, Verhalten und alle anderen Einstellungen beibehalten). Prüfen Sie den Diff, bevor Sie ihn übernehmen.

v1-Felder, die v2 ignoriert

Diese erzeugen eine Warnung und haben keine Wirkung:

Auch temperature, top_p und options auf Agent-Ebene wirken nicht mehr. v2 behält sie im request.body des Agents, sendet sie aber nicht. Setzen Sie sie stattdessen auf einer Modellvariante.

Diese v1-Felder wirken veraltet, funktionieren aber ohne Warnung weiter, weil v2 sie für Sie umwandelt. Löschen Sie sie beim Aufräumen nicht:

LSP-Config bleibt erhalten, wird aber nicht ausgeführt. Wenn Sie sich auf die LSP-Diagnosen von OpenCode verlassen haben, geben Sie dem Agent stattdessen explizite Lint-, Typecheck- oder Compiler-Befehle (zum Beispiel in AGENTS.md).

Schritt 5: Verhaltensänderungen, die später zuschlagen

Bei diesen Änderungen erscheint keine Fehlermeldung, deshalb sorgen sie für die meisten Überraschungen.

v2 liest CLAUDE.md nicht

v1 griff auf CLAUDE.md zurück, wenn keine AGENTS.md existierte. v2 tut das nicht. Liegen Ihre Projektregeln in CLAUDE.md, startet v2 ohne sie, und nichts warnt Sie. Die Lösung dauert eine Minute:

# In jedem Repo, das nur CLAUDE.md hat
git mv CLAUDE.md AGENTS.md

v1 nutzte außerdem ~/.claude/CLAUDE.md als globale Regeln, wenn ~/.config/opencode/AGENTS.md fehlte. Auch diesen Fallback hat v2 gestrichen. Wenn Sie keine globale AGENTS.md haben, kopieren Sie die Datei dorthin:

cp ~/.claude/CLAUDE.md ~/.config/opencode/AGENTS.md

Claude Code liest inzwischen AGENTS.md, wenn keine CLAUDE.md vorhanden ist. Eine Datei kann also weiterhin beide Tools bedienen. Der Feature-Request, den Fallback wiederherzustellen, ist als #53402 (opens in a new tab) offen.

Ordner außerhalb des Projekts sind standardmäßig erlaubt

In v1 fragte der Agent nach, bevor er ein Verzeichnis außerhalb des Projekts anfasste. In v2 ist der Zugriff auf externe Verzeichnisse standardmäßig erlaubt. Um das v1-Verhalten wiederherzustellen, fügen Sie diese Regel zu permissions hinzu:

{
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ]
}

Wenn Sie OpenCode mit Auto-Approve betreiben oder auf einem Rechner mit sensiblen Dateien außerhalb Ihrer Repos, fügen Sie diese Regel vor Ihrer ersten v2-Session hinzu.

Todos sind aus

Die Todo-Liste war in v1 standardmäßig an. In v2 ist sie aus. Mit "experimental": { "todo": true } schalten Sie sie wieder ein.

Ein Hintergrunddienst läuft jetzt für Ihr gesamtes Benutzerkonto

v2 startet einen gemeinsamen Hintergrundserver. TUI, Web-UI und Desktop-App verbinden sich alle damit. Das ermöglicht opencode pair (ein Einmal-Link, der nach 5 Minuten abläuft) und Hintergrundaufgaben (Ctrl+B). Wenn Sie ihn nicht wollen:

opencode service set disabled true   # stoppen und Autostart abschalten
opencode service unset disabled      # wieder einschalten
opencode --standalone                # ein privater Server nur für diesen Lauf

Pairing funktioniert nicht, solange der Dienst deaktiviert ist. Der Dienst liest außerdem cli.json nicht, Terminal-UI-Einstellungen wirken also nur im Terminal-Client.

Schritt 6: Plugins, Oh My OpenCode und die VS-Code-Extension

v1-Plugins laden in v2 nicht. Die Plugin-API ist neu. plugin in Ihrer Config in plugins umzubenennen reicht nicht. Der Code jedes Plugins muss portiert werden (siehe den offiziellen Plugin-Migrationsleitfaden (opens in a new tab)).

Der häufigste Ausfall war Oh My OpenCode (oh-my-openagent). Auf OpenCode 2.0.27 scheiterte Version 5.1.32 mit Plugin must export a default definition with an id and an effect or setup function (oh-my-openagent #10089 (opens in a new tab)). Der Fix (#10439 (opens in a new tab)) wurde am 18. Oktober gemergt, und 5.1.38 ist das erste npm-Release, das ihn enthält. Am 2. November bestätigte der Maintainer, dass aktuelle Versionen auf OpenCode 2 laden und einen Hinweis auf OmO Native anzeigen, die Standalone-App omo. Aktualisieren Sie oh-my-openagent auf 5.1.38 oder neuer, bevor Sie OpenCode upgraden. Wenn Sie lieber zu omo wechseln, führen Sie laut README einmal omo setup aus, um Provider-Keys, MCP-Server, Skills und Modellauswahl zu übernehmen. Wenn Sie das Harness selbst noch nicht kennen, beginnen Sie mit Oh My OpenCode und OpenCode: Installation, Setup und Fixes.

VS-Code-Extension-Fehler Unrecognized flag: --port. Ältere Versionen der Extension starten das CLI mit opencode --port <port>. v2 hat dieses Flag entfernt. Aktualisieren Sie die Extension auf v1.0.0 oder neuer (Marketplace oder Open VSX). Bis dahin öffnen Sie ein Terminal in VS Code und starten opencode selbst (#55219 (opens in a new tab)).

Eigene Skripte, die den Server aufrufen. Die v1-Server-API gibt es nicht mehr. Portieren Sie die Skripte auf das Paket @opencode/client, das den Hintergrunddienst auch selbst findet. In der Shell ruft opencode api dieselbe API auf. OPENCODE_SERVER_USERNAME wird nicht mehr unterstützt; der Benutzername ist immer opencode. Die OpenCode GitHub Action wurde in 2.2.0 entfernt.

Bekannte Probleme nach dem Upgrade

Das sind offene oder kürzlich behobene GitHub-Issues aus den ersten Wochen von 2.x. Die Fixes stammen von Maintainern, Meldern oder dem Bot des Projekts im jeweiligen Thread.

Rollback auf 1.x

Der Migrationsleitfaden behandelt den Weg zurück nicht. Das ist die sichere Reihenfolge:

1. v2 entfernen. opencode uninstall --dry-run zeigt, was entfernt wird. opencode uninstall entfernt dann das Programm und lässt Sessions, Config und Zustand auf der Platte.
2. v1 mit fester Version neu installieren: npm install -g opencode-ai@1.19.5 oder brew install anomalyco/tap/opencode (die Formel ohne -v2).
3. Falls Sie eine Config-Datei auf reine v2-Syntax umgestellt haben, stellen Sie sie aus ~/opencode-v1-config-backup wieder her.
4. Falls v1 die Session-Datenbank nicht lesen kann, nachdem v2 sie benutzt hat, stellen Sie ~/opencode-v1-data-backup wieder her. Wir haben nicht getestet, ob v1 eine Datenbank öffnet, in die v2 geschrieben hat. Verlassen Sie sich auf das Backup.

Sicherheitshinweis: der Einbruch in die OpenCode Console

Das ist unabhängig vom Upgrade, passierte aber in derselben Woche. Am 17. Oktober teilte das OpenCode-Team mit, dass sich jemand unbefugt Zugang zu einem Altsystem verschafft hatte, das gerade abgeschaltet wurde (auf Hacker News zitierte Mitteilung (opens in a new tab)). In einem Console-Workspace gespeicherte API-Keys von Drittanbietern "may have been exposed" (könnten offengelegt worden sein). Die Empfehlung: diese Keys im Dashboard jedes Providers widerrufen und ersetzen und die jüngste Nutzung prüfen. Ein späterer Beitrag bezifferte den Anteil betroffener Console-Nutzer auf 1,4 %, und Mitgründer Dax Raad sagte, CLI und Desktop-App seien nicht betroffen (TechCrunch (opens in a new tab)). Wenn Sie jemals OpenAI-, Anthropic- oder andere Keys in der Console gespeichert haben, rotieren Sie sie vor oder nach dem Upgrade.

Was in 2.0 wirklich neu ist

Für das Upgrade brauchen Sie nichts davon. Diese Funktionen erklären, warum sich die Architektur geändert hat:

• Hintergrunddienst, den TUI, Web-UI und Desktop-App gemeinsam nutzen, dazu opencode pair für den Webzugriff.
• Hintergrundaufgaben: Mit Ctrl+B schicken Sie einen laufenden Shell-Befehl oder Subagent in den Hintergrund, während der Haupt-Agent weiterarbeitet.
• Code Mode: macht aus MCP-Servern und OpenAPI-Endpunkten Funktionen, die der Agent in einem Schritt verketten kann. MCP-Server nutzen ihn standardmäßig.
• Hot Reload: OpenCode kann sich mitten in einer Session selbst ein Plugin schreiben und es sofort nutzen.
• @opencode/sdk und @opencode/client: der Code hinter dem CLI, um eigene Clients zu bauen.

Wenn Sie einen Terminal-Agent von Grund auf auswählen, statt einen bestehenden zu upgraden, ist Codex verwenden die naheliegendste Alternative.

Verwandte Guides

• Oh My OpenCode und OpenCode: Installation, Setup und Fixes
• Codex verwenden
• DeepSeek Harness verwenden
• Parallele Code-Agents erklärt