opencode verwenden: Schritt-für-Schritt-Anleitung

Um opencode zu verwenden, installierst du es mit einem Befehl, startest opencode in einem Projektordner, verbindest mit /connect einen Modellanbieter, wählst mit /models ein Modell und beschreibst, was du willst. Der Standard-Agent Build liest deinen Code, bearbeitet Dateien und führt Befehle aus. Drücke Tab, um zum Plan-Agenten zu wechseln, wenn du eine Änderung durchdenken willst, ohne Code anzufassen.

Das ist der Grundablauf. Diese Anleitung deckt den Rest ab: Anbieter und lokale Modelle, die TUI-Befehle für jeden Tag, die zwei eingebauten Agenten, opencode.json, AGENTS.md, MCP-Server, eigene Befehle und opencode neben anderen Agenten. Alles hier folgt der offiziellen Dokumentation von opencode mit Stand Oktober 2026.

Was opencode ist

opencode ist ein Coding-Agent für das Terminal, der nicht an ein einzelnes KI-Unternehmen gebunden ist. Claude Code nutzt Modelle von Anthropic, Codex Modelle von OpenAI. opencode baut auf dem AI SDK und Models.dev auf und funktioniert deshalb mit Dutzenden Anbietern und mit lokalen Modellen. Du kannst ein Modell zum Planen und ein anderes zum Bauen nutzen und den Anbieter wechseln, ohne ein neues Tool zu lernen.

Ein Hinweis zu den Versionen: opencode 2 ist erschienen, mit eigener Dokumentation. Beide Versionen installieren einen Befehl namens opencode, und du kannst nicht beide unter diesem Namen behalten. Diese Anleitung folgt Version 1, die das npm-Paket opencode-ai installiert. Das meiste gilt auch für Version 2. Hast du über die Core-Formula von Homebrew oder das Haupt-Repository von Arch installiert, hast du wahrscheinlich Version 2, also sieh in der passenden Dokumentation nach.

Schritt 1: opencode installieren

bun, pnpm und yarn global add opencode-ai funktionieren auch. Unter Windows empfiehlt die Dokumentation, opencode für das beste Ergebnis in WSL auszuführen. Ein modernes Terminal wie WezTerm, Alacritty, Ghostty oder Kitty stellt die TUI am besten dar.

opencode aktualisiert sich nie im Hintergrund. In einer Session installiert /update ein neueres Release von Version 1 oder bietet das Upgrade auf Version 2 an, wenn du schon die neueste Version 1 hast. In der Shell erledigt opencode upgrade dasselbe.

Schritt 2: Anbieter verbinden und Modell wählen

Wechsle in ein Projekt und starte opencode:

cd my-project
opencode

Führe dann /connect aus und wähle einen Anbieter. Dasselbe geht in der Shell mit opencode auth login. Die Zugangsdaten werden in ~/.local/share/opencode/auth.json gespeichert, und opencode auth list zeigt, was verbunden ist. opencode übernimmt außerdem API-Keys aus Umgebungsvariablen und aus einer .env-Datei im Projekt.

Ein paar gängige Optionen:

• OpenCode Zen: eine kuratierte Liste von Modellen, die das opencode-Team mit dem Agenten getestet hat. Melde dich auf opencode.ai/auth an, hinterlege eine Zahlungsmethode, kopiere den Key und füge ihn in /connect ein. Die Dokumentation empfiehlt das für neue Nutzer.
• Anthropic: Füge einen API-Key aus der Claude Console ein. Eine Anmeldung mit einem Claude-Pro- oder Max-Abo wird nicht angeboten. Anthropic erlaubt Drittanbieter-Tools nicht, diese Tarife so zu nutzen, und opencode liefert die Plugins, die das taten, nicht mehr aus.
• OpenAI: Wähle „ChatGPT Plus/Pro“, um dich im Browser anzumelden, oder gib einen API-Key von Hand ein.
• GitHub Copilot: Melde dich mit einem Gerätecode auf github.com/login/device an. Manche Modelle brauchen einen höheren Copilot-Tarif.
• Lokale Modelle: Füge einen eigenen Anbieter hinzu, der auf einen OpenAI-kompatiblen Server zeigt (siehe unten).

Ist ein Anbieter verbunden, öffnet /models (oder ctrl+x m) die Modellauswahl. In der Shell listet opencode models jedes Modell deiner Anbieter auf und opencode models anthropic die Modelle eines einzelnen Anbieters. Modelle schreibt man als provider/model, zum Beispiel anthropic/claude-sonnet-5-5. Viele Modelle haben Varianten, etwa mit höherem Reasoning-Effort, und ctrl+t schaltet durch sie durch.

Lokale Modelle mit Ollama

Ein lokales Modell ist ein eigener Anbieter in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

Schlagen Tool-Aufrufe mit einem lokalen Modell fehl, empfiehlt die Dokumentation, Ollamas num_ctx auf etwa 16k–32k zu erhöhen. Meist ist ein zu kleines Kontextfenster die Ursache. Wie du überhaupt ein lokales Modell auswählst, steht in lokale LLM-Coding-Agenten.

Schritt 3: TUI-Grundlagen

Der opencode-Bildschirm ist ein Chat mit deinem Projekt. Die paar Dinge, die du ständig brauchst:

• @ sucht unscharf nach Dateien und hängt sie an deine Nachricht.
• ! am Zeilenanfang führt einen Shell-Befehl aus, zum Beispiel !npm test, und fügt die Ausgabe in die Unterhaltung ein.
• ctrl+x ist die Leader-Taste. Die meisten Shortcuts sind ctrl+x gefolgt von einem Buchstaben.
• Bilder kannst du ins Terminal ziehen, um sie mitzuschicken.

/undo setzt Dateiänderungen über Git zurück, das Projekt sollte also ein Git-Repository sein. Um in der Shell dort weiterzumachen, wo du aufgehört hast, öffnet opencode -c die letzte Session und opencode -s <id> eine bestimmte. Für Skripte und CI führt opencode run "your prompt" eine einzelne Aufgabe ohne TUI aus.

Schritt 4: die Agenten Build und Plan

opencode hat zwei primäre Agenten, und Tab wechselt zwischen ihnen:

• Build ist der Standard. Bei ihm sind alle Tools aktiv: Er bearbeitet Dateien, führt Shell-Befehle aus und ruft MCP-Server auf.
• Plan ist eingeschränkt. Er kann deinen Code nicht bearbeiten; die einzigen Dateien, die er schreiben darf, sind Markdown-Pläne in .opencode/plans/. Er kann dir Rückfragen stellen.

Bei allem, was nicht trivial ist, lohnt es sich, in Plan anzufangen, sich auf einen Ansatz zu einigen, dann Tab zu drücken und Build die Umsetzung zu übergeben. Außerdem gibt es zwei Subagenten, die du mit @ aufrufst: @general für mehrstufige Recherche und Änderungen und @explore für schnelle Suchen im Code, die nur lesen. Jeder läuft in einer Kind-Session. ctrl+x und dann der Pfeil nach unten führt hinein, der Pfeil nach oben zurück zur Eltern-Session. Der Glossareintrag Subagent erklärt, warum das Kontext spart.

Eine Stolperfalle: Plan schränkt bash nicht von selbst ein. Shell-Befehle folgen deinen Berechtigungseinstellungen. Außerdem gilt ein "edit": "allow" auf oberster Ebene deiner Konfiguration auch für Plan, weil spätere passende Regeln gewinnen. Willst du Plan abriegeln, setze seine Berechtigungen direkt:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": "ask"
      }
    }
  }
}

Eigene Agenten erstellst du mit opencode agent create oder als Markdown-Dateien in .opencode/agents/ (pro Projekt) oder ~/.config/opencode/agents/ (global). Der Dateiname wird zum Namen des Agenten. Das Frontmatter legt description, mode (primary oder subagent), model und permission fest.

Schritt 5: die Konfigurationsdatei

opencode liest opencode.json (oder opencode.jsonc, das Kommentare erlaubt). Es gibt zwei übliche Orte:

• Global: ~/.config/opencode/opencode.json, für deine Standardwerte.
• Projekt: opencode.json im Projekt-Root, zusammen mit dem Code committet.

Die Dateien werden zusammengeführt, nicht ersetzt, und wo sie sich überschneiden, gewinnen die Projekteinstellungen. Eine praxistaugliche Projektkonfiguration:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "small_model": "anthropic/claude-haiku-5-5",
  "permission": {
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "npm test *": "allow"
    }
  },
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

• model ist das Standardmodell. small_model wird für leichte Aufgaben wie Session-Titel genutzt.
• permission nimmt pro Tool allow, ask oder deny, mit Mustern für bash. Das letzte passende Muster gewinnt, also setze "*" an den Anfang.
• instructions fügt zusätzlich zu AGENTS.md weitere Regeldateien hinzu. Globs und URLs funktionieren.

Werte können mit {env:VAR} aus der Umgebung oder mit {file:path} aus einer Datei kommen, Keys müssen also nie in der Konfiguration stehen. Standardmäßig sind die meisten Aktionen erlaubt. Beim Lesen von .env-Dateien und beim Zugriff auf Ordner außerhalb des Projekts wird zuerst gefragt. opencode --auto genehmigt alles, was nicht ausdrücklich verboten ist; nutze es also nur dort, wo du den Agenten ohne Aufsicht laufen lassen würdest.

TUI-Einstellungen wie Theme und Keybinds liegen in einer eigenen tui.json.

Schritt 6: AGENTS.md

AGENTS.md enthält deine Projektregeln: wie gebaut, getestet und gelintet wird, welche Konventionen gelten, welche Ordner tabu sind. Führe /init aus, und opencode durchsucht das Projekt und schreibt eine für dich. Lies sie, kürze sie und committe sie.

# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- API handlers live in src/api/; one file per route.
- Never edit files in src/generated/.

Globale Regeln für jedes Projekt kommen in ~/.config/opencode/AGENTS.md. Kommst du von Claude Code, greift opencode auf eine CLAUDE.md im Projekt zurück, wenn es keine AGENTS.md gibt, und liest auch ~/.claude/CLAUDE.md und ~/.claude/skills/. Setze OPENCODE_DISABLE_CLAUDE_CODE=1, um das abzuschalten. CLAUDE.md und AGENTS.md schreiben erklärt, was in die Datei gehört.

Schritt 7: MCP-Server

MCP-Server geben opencode neue Tools: einen Browser, einen Issue-Tracker, Dokumentationssuche. Sie kommen unter den Schlüssel mcp. Ein lokaler Server ist ein Befehl, den opencode startet; ein entfernter Server ist eine URL:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    },
    "my-remote": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MY_MCP_TOKEN}"
      }
    }
  }
}

opencode mcp add fügt einen Server interaktiv hinzu, und opencode mcp list zeigt, was eingerichtet ist und ob die Verbindung steht. Entfernte Server mit OAuth melden sich automatisch an, und opencode mcp auth <name> meldet dich von Hand an. opencode mcp debug <name> hilft, wenn ein Server sich nicht verbindet.

Jeder Server fügt seine Tools dem Kontext jeder Anfrage hinzu, und manche große, etwa der GitHub-MCP-Server, fügen viel hinzu. Schalte nur die Server ein, die du brauchst, und setze "enabled": false, um einen eingerichtet, aber ausgeschaltet zu lassen.

Schritt 8: eigene Befehle

Ein eigener Befehl ist ein Prompt, den du sonst immer wieder tippen würdest. Lege eine Markdown-Datei in .opencode/commands/ (pro Projekt) oder ~/.config/opencode/commands/ (global) ab; der Dateiname wird zum Befehl:

---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

Als .opencode/commands/test.md gespeichert, wird daraus /test. Befehle nehmen Argumente an: $ARGUMENTS ist alles nach dem Befehlsnamen, $1, $2 und so weiter sind einzelne Argumente, !`git diff --staged` fügt die Ausgabe eines Shell-Befehls ein, und @src/file.ts bindet eine Datei ein. Befehle kannst du auch unter dem Schlüssel command in opencode.json mit einem template definieren. Hat ein eigener Befehl denselben Namen wie ein eingebauter, gewinnt der eingebaute.

Häufige Stolperfallen

• „No provider“ beim ersten Start. Es ist noch nichts verbunden. Führe /connect aus.
• Bearbeitungen im Plan-Modus. Ein globales "edit": "allow" reicht auch bis zu Plan. Setze agent.plan.permission ausdrücklich.
• /undo setzt keine Dateien zurück. Der Ordner ist kein Git-Repository.
• Zwei opencode-Versionen kommen sich in die Quere. Homebrew Core installiert Version 2 und npm Version 1 unter demselben Befehlsnamen. Prüfe opencode --version und behalte nur eine.
• Langsame, teure Sessions. Zu viele MCP-Server oder eine lange Session. Schalte Server ab und nutze /compact oder /new.

opencode in AgentVera-Panes ausführen

Einer opencode-Session kann man leicht folgen. Mehrere Agenten gleichzeitig, manche mit opencode, manche mit Claude Code oder Codex, sind der Punkt, an dem Terminal-Tabs im Weg sind. AgentVera ist eine Desktop-App, die diese CLIs nebeneinander in echten Terminals ausführt, mit deinen eigenen Installationen und Logins. Die opencode-Unterstützung funktioniert so:

• Deine Anbieter, dein Login. Bei den Anbietern meldest du dich in opencode selbst an (/connect oder opencode auth login), und jeder verbundene Anbieter, lokale Modelle eingeschlossen, erscheint in der Modellliste von AgentVera, nach Anbieter gruppiert. Modellvarianten tauchen als Effort-Optionen auf. Ist opencode nicht installiert, installiert AgentVera es mit npm i -g opencode-ai.
• Eine Session pro Agent. Jeder opencode-Agent bekommt eine eigene Session, ein duplizierter Agent verzweigt also seine Unterhaltung, statt sie zu teilen. /compact funktioniert wie gewohnt.
• Deine opencode.json bleibt unberührt. Die Rolle des Agenten, die MCP-Server, die du im MCP-Manager von AgentVera hinzugefügt hast, und der Browser von AgentVera werden als zusätzliche Konfiguration übergeben und mit deiner zusammengeführt.
• Panes und Worktrees. Lass opencode im Raster des Workspace neben Claude Code laufen, jeden Agenten in seinem eigenen Git-Worktree, damit sie sich nicht gegenseitig die Dateien überschreiben.
• Review und Flows. opencode-Agenten funktionieren mit dem automatischen Code-Review, und in Flows (Pro und Team) kann die Antwort eines Agenten automatisch an einen anderen gehen. Zum Beispiel plant ein günstiges Modell und ein stärkeres baut.

Raster, Worktrees, Code-Review und MCP-Manager gehören zum Free-Tarif. Lade AgentVera herunter und probiere es aus. Wenn dein Team Claude auch in der CI einsetzt, deckt Claude Code GitHub Actions diese Seite ab, und Codex CLI nutzen ist dieselbe Anleitung für den Agenten von OpenAI.

Fazit

Um opencode zu verwenden, installierst du es, startest opencode in einem Projekt, verbindest mit /connect einen Anbieter und wählst mit /models ein Modell. Nutze Plan zum Nachdenken und Build zum Ändern von Code, und wechsle mit Tab zwischen beiden. Leg deine Standardwerte in opencode.json ab, deine Projektregeln in AGENTS.md, deine Tools unter mcp und deine wiederkehrenden Prompts in .opencode/commands/. Danach geht es bei opencode vor allem darum, für jede Aufgabe das richtige Modell zu wählen, und du kannst jederzeit wechseln.