OpenCode-Schnellstart: Installation, Konfiguration und Nutzung des Terminal-AI-Coding-Agenten

So installieren, konfigurieren und nutzen Sie OpenCode

Inhaltsverzeichnis

OpenCode ist ein Open-Source-KI-Coding-Agent, den Sie im Terminal (TUI + CLI) mit optionalen Desktop- und IDE-Oberflächen ausführen können. Dies ist der OpenCode-Quickstart: Installation, Überprüfung, Verbindung zu einem Modell/Anbieter und Ausführung echter Workflows (CLI + API).

Versionshinweis: OpenCode wird schnell aktualisiert. Die „neuesten" Befehle hier sind stabil, aber Ausgabe und Standardwerte können sich ändern – überprüfen Sie immer die offiziellen CLI-Dokumentationen und das Changelog (siehe unten).

Dieser Artikel ist Teil von KI-Entwickler-Tools: Der vollständige Guide zur KI-gestützten Entwicklung.

Was OpenCode ist (und wo es passt)

OpenCode ist für terminal-first, agentisches Coding konzipiert und bleibt dabei anbieter- und modellflexibel. In der Praxis ist es eine Workflow-Schicht, die Folgendes tun kann:

  • eine Terminal-Oberfläche starten, wenn Sie opencode ausführen
  • nicht-interaktive „One-Shot"-Prompts über opencode run ausführen (Skripte/Automatisierung)
  • einen headless HTTP-Server über opencode serve bereitstellen (und eine Web-Oberfläche über opencode web)
  • programmatisch über das offizielle JS/TS SDK @opencode-ai/sdk gesteuert werden

Wenn Sie es mit einem anderen Open-Source-Agent-Assistenten vergleichen möchten, der mehrstufige Pläne in einer sandboxed Umgebung ausführen kann, lesen Sie den OpenHands Coding Assistant QuickStart.

opencode mit self-hosted qwen3.5 27b LLM

Wenn Sie einen /ai-devtools/-Cluster aufbauen, ist OpenCode ein starker Kandidat für einen Subcluster, da er sich natürlich erweitert zu:

  • CLI-Tiefenanalyse
  • Modell-/Anbieter-Verhalten und Kosten (LLM-Vergleich innerhalb von OpenCode)
  • Konfiguration & Agenten
  • Integrationen (GitHub/GitLab/Copilot)
  • Cheatsheet
  • Oh My Opencode — eine Multi-Agenten-Orchestrierungsschicht, die auf OpenCode aufbaut

Voraussetzungen

Sie benötigen:

  • Einen modernen Terminal-Emulator (wichtig für das TUI-Erlebnis).
  • Zugriff auf mindestens ein Modell/einen Anbieter (API-Schlüssel oder Abonnement-Authentifizierung, je nach Anbieter). Lokale Optionen wie Ollama oder llama.cpp funktionieren ohne API-Schlüssel, wenn Sie lokal einen kompatiblen Server ausführen.

OpenCode installieren (Copy-Paste)

Offizielles Installationsskript (Linux/macOS/WSL):

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

Optionen für Paketmanager (offizielle Beispiele):

# Node.js globale Installation
npm install -g opencode-ai

# Homebrew (von OpenCode für die aktuellsten Releases empfohlen)
brew install anomalyco/tap/opencode

# Arch Linux (stabil)
sudo pacman -S opencode

# Arch Linux (aktuellste Version aus AUR)
paru -S opencode-bin

Hinweise zu Windows (offizielle Leitlinien empfehlen häufig WSL für beste Kompatibilität). Alternativen sind Scoop/Chocolatey oder npm.

# chocoloatey (Windows)
choco install opencode

# scoop (Windows)
scoop install opencode

Docker (nützlich für einen schnellen Test):

docker run -it --rm ghcr.io/anomalyco/opencode

Installation überprüfen

opencode --version
opencode --help

Erwartete Ausgabe (variiert je nach Version):

# Beispiel:
# <druckt eine Versionsnummer, z. B. vX.Y.Z>
# <druckt Hilfe mit verfügbaren Befehlen/Unterbefehlen>

Anbieter verbinden (zwei praktische Wege)

Weg A: TUI /connect (interaktiv)

Starten Sie OpenCode:

opencode

Dann ausführen:

/connect

Folgen Sie den Schritten in der Benutzeroberfläche, um einen Anbieter auszuwählen und sich zu authentifizieren (einige Workflows öffnen einen Browser/Geräteleist).

Weg B: CLI opencode auth login (Anbieter-Schlüssel)

OpenCode unterstützt die Konfiguration von Anbietern über:

opencode auth login

Hinweise:

  • Anmeldeinformationen werden in ~/.local/share/opencode/auth.json gespeichert.
  • OpenCode kann Schlüssel auch aus Umgebungsvariablen oder einer .env-Datei in Ihrem Projekt laden.

Lokale LLM-Hosting (Ollama, llama.cpp)

OpenCode funktioniert mit jeder OpenAI-kompatiblen API. Für die lokale Entwicklung führen viele Benutzer Ollama und zeigen OpenCode darauf. Ich hatte kürzlich sehr gute Erfahrungen mit der Konfiguration und Ausführung von OpenCode mit llama.cpp – llama-server stellt OpenAI-kompatible Endpunkte bereit, sodass Sie GGUF-Modelle mit demselben Workflow verwenden können. Wenn Sie eine feinere Kontrolle über Speicher und Laufzeit bevorzugen oder einen leichteren Stack ohne Python wünschen (Ollama ist übrigens in Go implementiert), ist llama.cpp einen Versuch wert. Ich habe die Möglichkeit, ausgelagerte Schichten zu konfigurieren, die Benutzerfreundlichkeit der Modelle im GGUF-Format und die deutlich bessere/schnellere Implementierung der Kompatibilität mit neuen Modellen wie Qwen3.5 sehr genossen. Wenn Sie wissen möchten, welche Modelle in OpenCode tatsächlich gute Ergebnisse liefern – bei Coding-Aufgaben und der Genauigkeit strukturierter Ausgaben – sehen Sie meinen hands-on LLM-Vergleich für OpenCode.

Ein Projekt korrekt starten (empfohlener erster Lauf)

Von Ihrem Repository aus:

cd /path/to/your/repo
opencode

Dann initialisieren:

/init

Dies analysiert Ihr Projekt und erstellt eine AGENTS.md-Datei im Projektstammverzeichnis. Es ist typischerweise sinnvoll, diese Datei zu committen, damit OpenCode (und Teammitglieder) einen konsistenten Projektkontext teilen.

Kern-CLI-Workflows (Copy-Paste-Beispiele)

OpenCode unterstützt nicht-interaktive Ausführungen:

opencode run "Erkläre, wie Closures in JavaScript funktionieren"

Workflow: Code generieren (CLI)

Ziel: Eine kleine, testbare Funktion mit minimalem Kontext generieren.

opencode run "Schreibe eine Go-Funktion ParsePort(envVar string, defaultPort int) (int, error). Sie sollte die Umgebungsvariable lesen, eine Ganzzahl parsen, 1-65535 validieren und defaultPort zurückgeben, wenn leer. Inklusive 3 tabelle-gesteuerten Tests."

Erwartete Ausgabe:

  • Eine Erklärung plus Code-Blöcke (Funktion + Tests). Der genaue Code variiert je nach Modell/Anbieter und Prompt.

Workflow: Eine Datei sicher refaktorisieren (CLI + Plan-Agent)

Ziel: Refaktorierung ohne versehentliche Änderungen durch Verwendung eines restriktiveren Agenten.

opencode run --agent plan --file ./src/auth.ts \
  "Refaktorisiere diese Datei, um die Komplexität zu reduzieren. Ausgabe: (1) ein kurzer Plan, (2) ein unified diff Patch, (3) Risiken/Grenzfälle zum Testen. Führe keine Befehle aus."

Erwartete Ausgabe:

  • Ein Plan-Abschnitt + ein diff --git ...-Patch-Block + eine Test-Checkliste.
  • Der Inhalt variiert. Wenn kein Diff erzeugt wird, prompten Sie erneut: „Gib nur einen unified diff zurück" oder „Verwende das Format diff --git."

Workflow: Repository-Fragen stellen (CLI)

Ziel: Implementierungsdetails schnell finden.

opencode run --agent explore \
  "In diesem Repository, wo wird die Authentifizierung für API-Anfragen validiert? Liste wahrscheinlich Dateien auf und erkläre den Ablauf. Falls unsicher, sage, was du geprüft hast."

Erwartete Ausgabe:

  • Eine kurze Karte von Dateipfaden + Ablaufbeschreibung.
  • Die Ausgabe hängt von der Repository-Größe und den Kontext-Tools des Modells/Anbieters ab.

Workflow: Wiederholte CLI-Ausführungen mit einem persistenten Server beschleunigen

Wenn Sie Skripte schreiben oder mehrere opencode run-Aufrufe ausführen, können Sie einen headless Server einmal starten:

Terminal 1:

opencode serve --port 4096 --hostname 127.0.0.1

Terminal 2:

opencode run --attach http://localhost:4096 "Fasse die Repository-Struktur und Haupteinstiegspunkte zusammen."
opencode run --attach http://localhost:4096 "Schlage jetzt 3 hochwirksame Refaktorierungen vor und warum."

Erwartete Ausgabe:

  • Gleich wie opencode run, aber in der Regel mit weniger wiederholtem Start-Overhead.

Programmatische Nutzung (offizielles JS/TS SDK)

OpenCode stellt einen HTTP-Server (OpenAPI) bereit und bietet einen typesicheren JS/TS-Client.

Installieren:

npm install @opencode-ai/sdk

Beispiel: Server + Client starten, dann prompten

Erstellen Sie scripts/opencode-sdk-demo.mjs:

import { createOpencode } from "@opencode-ai/sdk";

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    // Modellstring-Format ist provider/model (Beispiel)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`Server läuft unter: ${opencode.server.url}`);

// Grundlegender Gesundheits-/Versionscheck
const health = await opencode.client.global.health();
console.log("Gesund:", health.data.healthy, "Version:", health.data.version);

// Sitzung erstellen und prompten
const session = await opencode.client.session.create({ body: { title: "SDK Quickstart Demo" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Generiere einen kleinen README-Abschnitt, der dieses Repository beschreibt." }],
  },
});

console.log(result.data);

// Server schließen, wenn fertig
opencode.server.close();

Ausführen:

node scripts/opencode-sdk-demo.mjs

Erwartete Ausgabe:

  • „Server läuft unter …"
  • Eine Gesundheitsantwort, einschließlich einer Versionsstring
  • Eine Sitzungs-Prompt-Antwort (genau Struktur hängt von responseStyle und SDK-Version ab)

Minimale OpenCode-Konfiguration zum Kopieren

OpenCode unterstützt JSON und JSONC-Konfiguration. Dies ist ein vernünftiger Ausgangspunkt für eine projektlokale Konfiguration.

Erstellen Sie opencode.jsonc im Stammverzeichnis Ihres Repositories:

{
  "$schema": "https://opencode.ai/config.json",

  // Wähle ein Standardmodell (provider/model). Halte dies mit dem, was `opencode models` zeigt, synchron.
  "model": "provider/model",

  // Optional: ein günstigeres „kleines Modell" für leichte Aufgaben (Titel usw.)
  "small_model": "provider/small-model",

  // Optional: OpenCode-Server-Standardwerte (verwendet von serve/web)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

  // Optionale Sicherheit: Bestätigung vor Änderungen/Befehlen erfordern
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Kurzes Cheatsheet (Schnellreferenz)

Befehle, die Sie täglich verwenden werden

opencode                       # TUI starten
opencode run "..."             # nicht-interaktive Ausführung (Automatisierung)
opencode run --file path "..." # Dateien an Prompt anhängen
opencode models --refresh      # Modellliste aktualisieren
opencode auth login            # Anbieter-Anmeldedaten konfigurieren
opencode serve                 # headless HTTP-Server (OpenAPI)
opencode web                   # headless Server + Web-Oberfläche
opencode session list          # Sitzungen auflisten
opencode stats                 # Token/Kosten-Statistiken

TUI-Befehle, die sich zu merken lohnen

/connect   # einen Anbieter verbinden
/init      # Repository analysieren, AGENTS.md generieren
/share     # eine Sitzung teilen (falls aktiviert)
/undo      # eine Änderung rückgängig machen
/redo      # eine Änderung wiederherstellen
/help      # Hilfe/Verknüpfungen

Konzept des Standard-“Leader-Keys” (TUI)

OpenCode verwendet eine konfigurierbare “Leader”-Taste (häufig ctrl+x), um Terminal-Konflikte zu vermeiden. Viele Verknüpfungen sind “Leader + Taste”.

Einseitiges druckbares OpenCode-Cheatsheet-Tabellen

Diese Version ist bewusst dicht und “druckfreundlich”. (Sie können sie später in eine dedizierte /ai-devtools/opencode/cheatsheet/-Seite kopieren.)

Aufgabe Befehl / Verknüpfung Hinweise
TUI starten opencode Standardverhalten ist das Starten der Terminal-Oberfläche
One-Shot-Prompt ausführen opencode run "..." Nicht-interaktiver Modus für Skripting/Automatisierung
Datei(en) an Prompt anhängen opencode run --file path/to/file "..." Verwenden Sie mehrere --file-Flags für mehrere Dateien
Modell für einen Lauf wählen opencode run --model provider/model "..." Modellstrings sind provider/model
Agent wählen opencode run --agent plan "..." Plan ist für sicherere “keine Änderungen”-Arbeit konzipiert (permission-restricted)
Modelle auflisten opencode models [provider] Verwenden Sie --refresh, um die zwischengespeicherte Liste zu aktualisieren
Anbieter-Anmeldedaten konfigurieren opencode auth login Speichert Anmeldedaten in ~/.local/share/opencode/auth.json
Authentifizierte Anbieter auflisten opencode auth list / opencode auth ls Bestätigt, was OpenCode sieht
Headless-Server starten opencode serve --port 4096 --hostname 127.0.0.1 OpenAPI-Spezifikation unter http://host:port/doc
Läufe an Server anhängen opencode run --attach http://localhost:4096 "..." Hilft, wiederholte kalte Starts zu vermeiden
Basis-Auth aktivieren OPENCODE_SERVER_PASSWORD=... opencode serve Benutzername standardmäßig opencode, es sei denn, überschrieben
Web-Oberflächen-Modus opencode web Startet Server und öffnet Browser
Sitzung exportieren opencode export [sessionID] Nützlich zum Archivieren oder Teilen von Kontext
Sitzung importieren opencode import session.json Kann auch von einer Share-URL importiert werden
Globale CLI-Flags anzeigen opencode --help / opencode --version --print-logs + --log-level zum Debuggen
TUI Leader-Key-Konzept Standard-Leader-Key oft ctrl+x In tui.json anpassbar

Oh My Opencode — OpenCode mit Multi-Agenten-Orchestrierung erweitern

Sobald OpenCode läuft, ist der natürliche nächste Schritt Oh My Opencode — ein Community-Plugin, das OpenCode in einem Multi-Agenten-Harness einhüllt. Die Hauptidee: Geben Sie ultrawork (oder ulw) in einer Sitzung ein, und ein Orchestrator (Sisyphus) übernimmt, delegiert Unteraufgaben an Spezialisten-Agenten, die parallel laufen, jeweils auf der Modellfamilie, für die ihre Prompts optimiert sind.

Drei Artikel behandeln dies im Detail:

Quellen (zuerst offiziell)

Offiziell:

Autoritative Integrationsreferenz:

Glaubwürdige Vergleiche/Tutorials: