Human Agent Interface / Tutorials / OpenCode Referenz

OpenCode Harness — Referenz-Guide

Stand: März 2026. Aus der täglichen Praxis mit OpenCode; Flags, Preise und Bugs können sich seitdem geändert haben. Siehe auch: OpenCode Tutorial.

Für alle, die Claude Code gut kennen: Dieser Guide erklärt OpenCode im direkten Vergleich.

1. Architektur

OpenCode ist ein autonomer Coding-Agent mit TUI-Frontend und headless-fähigem Backend.

opencode (CLI)
├── TUI              — interaktive Terminal-UI (Standard bei `opencode`)
├── opencode run     — one-shot Execution (kein TUI)
├── opencode serve   — headless HTTP-Server
├── opencode web     — Web-UI
└── opencode acp     — ACP-Protocol für Editor-Integration

Config-Schichten (von global nach lokal):

Layer Pfad Scope
Credentials ~/.local/share/opencode/auth.json Provider-Auth
Globale Config ~/.config/opencode/ User-weit
Projekt-Config ./opencode.json Per-Project (override)
Plugins ./plugins/*.ts Per-Project TypeScript Hooks
Commands ./commands/ Custom Slash-Commands

Agent-System: 5 Built-in Agents (build, plan, summary, title, compaction) + Subagents (explore, general). Kein Equivalent zu Claude Codes 21 Markdown-Agenten — OpenCode-Agents sind codebasiert, nicht deklarativ konfigurierbar (außer via opencode agent create).

Storage: SQLite DB unter ~/.local/share/opencode/opencode.db + JSON-Snapshots. Sessions persistieren lokal, aber kein Gedächtnis zwischen opencode run-Aufrufen.

2. Konfiguration

Minimale opencode.json:

{
  "$schema": "https://opencode.ai/schema/config.json",
  "provider": {
    "anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" }
  },
  "model": {
    "default": { "provider": "anthropic", "model": "claude-sonnet-4-5" },
    "fast":    { "provider": "anthropic", "model": "claude-haiku-4-5-20251001" }
  },
  "permission": "allow"
}

Permission-Modi ("permission" Key):

Modus Verhalten Empfohlen für
ask Fragt bei unbekannten Ops (Default) Interaktiv/TUI
auto-edit Edits erlaubt, Shell-Ops werden gefragt Semi-automatisch
allow Alles erlaubt ohne Rückfrage Headless/CI

Wichtig: Ohne "permission": "allow" in headless-Szenarien können Sessions blockieren — OpenCode wartet auf manuelle Bestätigung.

MCP-Server einbinden:

{
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Projekte"]
    }
  }
}

Experimental Plugins (TypeScript Hooks):

{
  "experimental": {
    "chat": {
      "system": { "transform": "plugins/context-injection.ts" }
    }
  }
}

3. Tuning

Modell wählen

# CLI-Flag (override für einzelnen Lauf)
opencode run "prompt" -m anthropic/claude-opus-4-6

# Reasoning-Varianten (für Modelle mit Extended Thinking)
opencode run --variant high    "..."   # 16K Reasoning Tokens
opencode run --variant max     "..."   # 31.9K Reasoning Tokens
opencode run --variant minimal "..."   # kein Reasoning

Multi-Provider — der echte Vorteil gegenüber Claude Code

{
  "provider": {
    "anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" },
    "openai":    { "apiKey": "${OPENAI_API_KEY}" },
    "minimax":   { "apiKey": "${MINIMAX_API_KEY}" }
  }
}

MiniMax kostet ca. $0.10/1M Tokens — ~150x günstiger als Opus. Sinnvoll für Batch-Tasks ohne Qualitätsanspruch.

Agent auswählen

opencode run --agent explore "..."  # Explore-Agent (darf fragen, kein Edit)
opencode run --agent build  "..."  # Build-Agent (volle Rechte)
opencode agent create               # Custom Agent anlegen
opencode agent list                 # Verfügbare Agents zeigen

Agent-Permissions im Überblick:

Permission build plan explore general
bash allow allow allow allow
edit context context deny deny
external_dir ask ask ask ask
question deny deny allow allow

Context-Injection via Plugin

Kein CLAUDE.md-Equivalent — Kontext muss über TypeScript-Hook injiziert werden:

// plugins/context-injection.ts
export default function transform(system: string): string {
  return system + "\n\n# Projekt-Regeln\n- Kein apt ohne Rückfrage\n- Tests vor Commit";
}

Parallele Runs

# Mehrere one-shot Tasks gleichzeitig — OpenCode unterstützt parallele Instanzen
opencode run "Task A" &
opencode run "Task B" &
wait

Debug

opencode debug config           # Resolved Config anzeigen (inkl. Env-Var-Expansion)
opencode debug paths            # Alle relevanten Dateipfade
opencode debug agent build      # Agent-Details: System-Prompt, Permissions
opencode debug lsp              # LSP-Status

4. Vor- und Nachteile

Vorteile

Feature Bewertung
Multi-Provider Nicht auf Anthropic locked — OpenAI, MiniMax, Custom-Endpoints möglich
Kosten MiniMax ~$0.10/1M Tokens für Batch-Tasks
One-shot opencode run ideal für skriptbare Pipelines
Parallele Instanzen Mehrere Runs gleichzeitig ohne Konflikte
Server-Mode opencode serve für API-basierte Integration
Debug-Tools opencode debug deckt Config, Paths, Agents ab
MCP native CLI-Management von MCP Servern ohne JSON-Editierung
Reasoning-Varianten high/max/minimal direkt als Flag

Nachteile — ehrliche Einschätzung

Problem Konsequenz
Fragt NICHT nach Unvollständiges Briefing → falsches Produkt. OpenCode baut, was es versteht — nicht was du meinst.
Schwache Feedback-Annahme Korrekturen werden bestätigt, nicht wirklich integriert ("Verstanden, soll ich nochmal?")
Scope-Drift Ohne explizites Scope-Statement erweitert OpenCode selbstständig den Auftrag
Kein Session-Gedächtnis opencode run startet jedes Mal blank — kein Kontext aus Vorläufen
Plugins experimental Hooks weniger mächtig als Claude Codes 5-Punkt-Lifecycle (PreToolUse, PostToolUse etc.)
Kein deklaratives Regelwerk Kein CLAUDE.md-Equivalent — Regeln müssen per Hook injiziert werden
Keine Subagent-Orchestrierung Agents sind intern; kein paralleles Agent-Spawning wie in Claude Code möglich

Fazit: OpenCode ist stark für gut-spezifizierte one-shot Tasks, Multi-Provider-Flexibilität und headless Pipelines. Für komplexe, iterative Arbeit mit Kontext-Aufbau bleibt Claude Code überlegen.

5. Referenz

Dateipfade

Pfad Inhalt
./opencode.json Projekt-Config (per-project override)
~/.config/opencode/ Globale Config
~/.local/share/opencode/ Data-Root
~/.local/share/opencode/auth.json Provider-Credentials
~/.local/share/opencode/opencode.db SQLite Session-DB
./plugins/ TypeScript Hooks (per-project)
./commands/ Custom Slash-Commands (per-project)

Wichtige Befehle

# Starten
opencode                                  # TUI
opencode run "prompt"                     # One-shot
opencode run "prompt" -m provider/model   # Mit Modell-Auswahl
opencode run --variant max "prompt"       # Max Reasoning
opencode serve --port 4096                # Headless Server

# Provider & Modelle
opencode providers list                   # Konfigurierte Provider
opencode providers login anthropic        # Auth-Flow
opencode models anthropic                 # Verfügbare Modelle für Provider

# MCP
opencode mcp list                         # Konfigurierte MCP Server
opencode mcp add name -- command          # MCP Server hinzufügen
opencode mcp remove name                  # MCP Server entfernen

# Agents
opencode agent list                       # Verfügbare Agents
opencode agent create                     # Custom Agent anlegen

# Debug
opencode debug config                     # Resolved Config
opencode debug paths                      # Alle Pfade
opencode debug agent <name>               # Agent-Details
opencode debug lsp                        # LSP-Status
opencode debug skill                      # Skill-Status

Stand: 2026-03 — Getestet gegen OpenCode MCP-Server und Harness-Evals im harness-tutorials Projekt.