OpenHands Coding Assistant – Schnellstart: Installation, CLI-Parameter, Beispiele

OpenHands ist eine Open-Source-Plattform, die modellagnostisch für KI-gesteuerte Softwareentwicklungs-Agenten ist. Sie ermöglicht es einem Agenten, sich mehr wie ein Coding-Partner als wie ein einfaches Autovervollständigungstool zu verhalten.

Er kann mit Dateien arbeiten, Befehle in einer sandboxierten Umgebung ausführen und bei Bedarf Web-Browsing nutzen.

Dieser QuickStart konzentriert sich auf die OpenHands-CLI, da dies der schnellste Weg ist, um sich direkt aus dem Terminal produktiv zu machen, und er passt sauber auf Automatisierungsmuster wie Skripte und CI-Läufe auf. Für einen breiteren Überblick über das Feld, siehe KI-Entwickler-Tools: Der vollständige Guide zu KI-gestützter Entwicklung.

Was OpenHands ist und was es anders macht

Ein KI-Coding-Assistent hilft typischerweise dabei, Code mit einem Sprachmodell zu generieren oder zu bearbeiten. OpenHands erweitert diese Idee zu einem „agentischen" Workflow: Das System kann iterativ planen, Aktionen ausführen (wie das Schreiben von Dateien oder das Ausführen von Tests), Ergebnisse beobachten und fortfahren, bis die Aufgabe abgeschlossen ist.

OpenHands ist auch weit verbreitet als das Projekt bekannt, das früher OpenDevin hieß, und es hat sich zu einer community-getriebenen Plattform entwickelt, die mehrere Nutzungsweisen bietet: eine CLI, eine lokale Web-GUI, eine cloud-hosted UI und eine SDK.

Aus technischer Sicht ist der entscheidende Unterschied, dass OpenHands um eine Ausführumgebung (eine Sandbox) herum gebaut ist, sodass ein Agent Befehle und Tools sicher ausführen kann, anstatt nur Text zu produzieren. Die OpenHands-Paper beschreibt eine Docker-sandboxierte Laufzeitumgebung mit Shell- und Browsing-Fähigkeiten, speziell zur Unterstützung realistischer, entwicklerähnlicher Interaktionsmuster.

OpenHands-CLI installieren

OpenHands unterstützt mehrere Installationsmethoden. Für die meisten Entwickler ist es am besten, mit einer lokalen CLI-Installation zu beginnen (schnelle Iteration) und optional später Docker-basierte Workflows hinzuzufügen, wenn Sie eine strikte Isolation bei der Ausführung wünschen.

Installation mit uv

Die aktuellen OpenHands-CLI-Dokumente empfehlen die Installation mit uv und erfordern Python 3.12+.

uv tool install openhands --python 3.12
openhands

Das Aktualisieren ist ebenso einfach.

uv tool upgrade openhands --python 3.12

Warum uv in der Praxis wichtig ist: uv bietet eine bessere Isolation von Ihrer aktuellen Projektumgebung und ist für Standard-MCP-Server erforderlich.

Die eigenständige CLI-Binärdatei installieren

Wenn Sie einen Installationsfluss mit „einem einzigen Befehl" wünschen, stellt OpenHands ein Installationsskript zur Verfügung.

curl -fsSL https://install.openhands.dev/install.sh | sh
openhands

Unter macOS müssen Sie möglicherweise die Binärdatei in „Datenschutz & Sicherheit" explizit erlauben, bevor sie ausgeführt wird.

Über Docker für Isolation ausführen

Wenn Sie die Installation lieber enthalten halten möchten, zeigen die CLI-Dokumente auch einen docker-basierten Flow. Dieser Ansatz stützt sich auf das Mounten eines Verzeichnisses, auf das OpenHands zugreifen soll, und das Weitergeben Ihrer Benutzer-ID, um das Erstellen von root-eigenen Dateien im gemounteten Arbeitsbereich zu vermeiden.

export SANDBOX_VOLUMES="$PWD:/workspace"

docker run -it \
  --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.12.0-python \
  -e SANDBOX_USER_ID=$(id -u) \
  -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/root/.openhands \
  --add-host host.docker.internal:host-gateway \
  --name openhands-cli-$(date +%Y%m%d%H%M%S) \
  python:3.12-slim \
  bash -c "pip install uv && uv tool install openhands --python 3.12 && openhands"

Erster Lauf-Konfiguration und wo Einstellungen gespeichert werden

Beim ersten Lauf führt die CLI Sie durch die Konfiguration der erforderlichen LLM-Einstellungen und speichert diese für zukünftige Sitzungen. Die CLI-Dokumente geben an, dass Einstellungen unter ~/.openhands/settings.json gespeichert werden und der Gesprächsverlauf in ~/.openhands/conversations gespeichert ist, aber als ich OpenHands gerade erst kürzlich installiert habe, wurde die Konfiguration in ~/.openhands/agent_settings.json gespeichert, sodass die Dokumente vielleicht nicht ganz richtig sind.

Für tiefere Konfiguration und Tooling-Integration dokumentiert OpenHands auch zusätzliche Konfigurationsdateien wie ~/.openhands/agent_settings.json (Agent- und LLM-Einstellungen), ~/.openhands/cli_config.json (CLI-Präferenzen) und ~/.openhands/mcp.json (MCP-Server).

OpenHands mit lokaler Ollama und llama.cpp konfigurieren

OpenHands funktioniert mit jedem OpenAI-kompatiblen lokalen Backend — Ollama, LocalAI, llama.cpp und andere. Wenn Sie nicht sicher sind, was Sie verwenden sollen, siehe Ollama vs vLLM vs LM Studio: Beste Art, LLMs lokal auszuführen für einen Vergleich.

Wenn Sie OpenHands zum ersten Mal starten, zeigt es Ihnen die Einstellungsseite an, Wenn Sie diese erste Phase bereits bestanden haben, können Sie diese Seite erneut öffnen, indem Sie /settings tippen und dann ctrl+j drücken. Geben Sie nun ein:

• im Feld Custom Model: ollama/devstral-small-2:24b, oder was auch immer Ihr Lieblings-Local-Modell ist,
• und im Feld Base Url: http://localhost:11434

Für eine schnelle Referenz zu Ollama-Befehlen, siehe das Ollama-CLI-Cheat-Sheet: serve, run, ps und Modellverwaltung.

Um die OpenHands-Konfigurationsdatei manuell zu bearbeiten, zum Beispiel wenn Ihnen die Einstellungsseite nicht gefällt, führen Sie aus:

nano ~/.openhands/agent_settings.json

oder wenn Sie einen Editor mit mehr GUI bevorzugen:

gedit GUI ~/.openhands/agent_settings.json

Es gibt eine LLM-Eigenschaft an zwei Stellen, ich habe sie so eingestellt, dass sie unter anderem diese Untereigenschaften haben, um auf Ollama zu zeigen:

"llm":{"model":"ollama/devstral-small-2:24b","api_key":"aaa","base_url":"http://localhost:11434"

Um OpenHands auf eine lokale llama.cpp-Instanz zu zeigen – dasselbe, an zwei Stellen:

"llm":{"model":"openai/devstral-small-2:24b","api_key":"aaa","base_url":"http://localhost:11434"

Um mich mit llama.cpp zu verbinden, habe ich konfiguriert:

• “model”:“openai/Qwen3.5-35B-A3B-UD-IQ3_S.gguf”
• “base_url”:“http://localhost:8080/v1”

und habe llama.cpp mit dem Befehl gestartet (siehe llama.cpp Quickstart mit CLI und Server für Flaggen-Details):

./llama.cpp/llama-server \
    -m /mnt/ggufs/Qwen3.5-35B-A3B-UD-IQ3_S.gguf \
    --ctx-size 70000 \
    -ngl 40 \
    --temp 0.6 \
    --top-p 0.95 \
    --top-k 20 \
    --min-p 0.00

OpenHands konnte sich damit erfolgreich mit meiner Testanfrage verbinden: Erstelle für mich ein CLI-Tool in Go, das die IndexNow-Endpunkte von Bing und anderen Suchmaschinen aufruft, um über Änderungen auf meiner Website zu benachrichtigen – mit Quellcode, ausführbarer Datei und README.md.

Wie die OpenHands-CLI in der Praxis funktioniert

Der Standardbefehl openhands startet ein interaktives Terminal-Erlebnis. OpenHands bietet eine Befehlsleiste und Befehle innerhalb der Sitzung, sodass Sie den Agenten schnell steuern können, während er arbeitet.

Nützliche interaktive Steuerungen, die man früh kennen sollte, umfassen das Öffnen der Befehlsleiste, das Pausieren des Agenten und das Verlassen der App.

• Ctrl+P öffnet die Befehlsleiste.
• Esc pausiert den laufenden Agenten.
• Ctrl+Q oder /exit beendet die CLI.

Innerhalb der CLI unterstützt OpenHands auch schrägstrich-präfixierte Befehle wie /help, /new und /condense, was wertvoll ist, wenn Sie lange Gespräche führen möchten, ohne neu zu starten.

OpenHands hört nicht bei einer Terminal-Oberfläche auf. Die CLI umfasst mehrere Schnittstellen, die gut auf verschiedene Entwickler-Workflows passen:

• Headless-Modus für Automatisierung und CI.
• Web-Schnittstelle zum Ausführen des CLI-Erlebnisses in einem Browser.
• GUI-Server für die vollständige lokale Webanwendung, gestartet über Docker.
• IDE-Integration über ACP für editorbasierte Workflows.

Hauptkommandozeilenparameter, die Sie tatsächlich verwenden werden

Auf einer hohen Ebene folgt die OpenHands-CLI diesem Muster:

openhands [OPTIONS] [COMMAND]

Das umfasst globale Optionen (Dinge wie Aufgaben, Fortsetzen, headless), plus Unterbefehle (serve, web, cloud, acp, mcp, login, logout).

Kernoptionen für die tägliche Arbeit

Die am häufigsten verwendeten Globals sind:

• -t, --task, um das Gespräch mit einer Anfangsaufgabe zu säen.
• -f, --file, um aus einer Datei zu säen, was hilfreich ist, wenn Sie Aufgaben in einer Versionskontrolle festlegen möchten.
• --resume [ID] und --last, um vorherige Läufe fortzusetzen.
• --headless für nicht-interaktive Ausführung, typischerweise in der Automatisierung.
• --json, um JSONL-Ausgabe im Headless-Modus zum maschinellen Parsen zu streamen.

Sicherheit und Genehmigungen sind ebenfalls erstklassig:

• --always-approve genehmigt Aktionen automatisch, ohne abzufragen.
• --llm-approve verwendet einen LLM-basierten Sicherheitsanalysator für die Genehmigung von Aktionen.

Modell- und Provider-Konfiguration über Umgebungsvariablen

OpenHands unterstützt Umgebungsvariablen für die Modellkonfiguration:

• LLM_API_KEY setzt Ihren Provider-API-Schlüssel.
• LLM_MODEL und LLM_BASE_URL können als Überschreibungen angewendet werden, wenn Sie openhands --override-with-envs ausführen.

Beispiel für den Überschreibungsfluss:

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="your-api-key"
openhands --override-with-envs

OpenHands bemerkt ausdrücklich, dass Überschreibungen, die mit --override-with-envs angewendet werden, nicht persistent sind.

Unterbefehle, die es wert sind, zu kennen

Sie brauchen nicht jeden Unterbefehl am ersten Tag, aber dies sind die, die schnell ins Spiel kommen:

• openhands serve startet den vollständigen GUI-Server unter Verwendung von Docker, typischerweise erreichbar unter http://localhost:3000, mit Optionen wie --mount-cwd und --gpu.
• openhands web startet die CLI als browserzugängliche Webanwendung, standardmäßig auf Port 12000.
• openhands login authentifiziert sich mit OpenHands Cloud und lädt Ihre Einstellungen.
• openhands cloud erstellt eine neue Konversation in OpenHands Cloud aus der CLI.

Copy-and-Paste-Beispiele, die Sie sofort verwenden können

Der schnellste Weg, um Wert aus OpenHands zu ziehen, ist, es wie einen aufgabengetriebenen Coding-Agenten zu behandeln. Halten Sie Aufgaben knapp, schließen Sie Dateinamen ein und bitten Sie bei Bedarf um Tests oder Verifizierung.

Eine interaktive Coding-Sitzung mit einer Anfangsaufgabe starten

Dies ist das „Standard-Entwickler-Erlebnis" und eines der häufigsten Muster.

openhands -t "Fix the bug in auth.py and add a regression test"

Die OpenHands-CLI-Dokumentation zeigt genau diese Idee für das Bootstrapping einer Sitzung mit -t.

Eine Aufgabe aus einer Datei säen

Das Verwenden einer Datei ist nützlich, wenn Sie Wiederholbarkeit, Team-Review oder CI-Wiederverwendung wünschen.

cat > task.txt << 'EOF'
Refactor the database connection module.
Add unit tests and ensure the test suite passes.
EOF

openhands -f task.txt

Das CLI-Quick-Start unterstützt explizit das Starten aus einer Aufgabedatei mit -f.

Im Headless-Modus für CI oder Automatisierung ausführen

Der Headless-Modus läuft ohne die interaktive UI und ist für CI-Pipelines und automatisiertes Skripten gebaut.

openhands --headless -t "Add unit tests for auth.py and run them"

Zwei wichtige technische Realitäten hier:

• Der Headless-Modus erfordert --task oder --file.
• Der Headless-Modus läuft immer im Always-Approve-Modus und kann nicht geändert werden, und --llm-approve ist im Headless-Modus nicht verfügbar. Behandeln Sie es als leistungsstarke Automatisierung und führen Sie es in einer kontrollierten Umgebung aus.

Um die Integration mit Log-Parsing oder anderen Tools zu ermöglichen, aktivieren Sie die JSONL-Ausgabe:

openhands --headless --json -t "Create a simple Flask app with healthcheck endpoint" > openhands-output.jsonl

OpenHands dokumentiert --json als JSONL-Ereignis-Streaming im Headless-Modus und zeigt das Umleiten der Ausgabe in eine Datei.

Arbeit fortsetzen, ohne Kontext zu verlieren

Das Fortsetzen ist entscheidend, sobald Sie OpenHands für nicht-triviale Änderungen verwenden.

Liste recente Konversationen auf:

openhands --resume

Die jüngste fortsetzen:

openhands --resume --last

Oder eine spezifische Konversations-ID fortsetzen:

openhands --resume abc123def456

Diese Flows sind in der CLI-Befehlsreferenz und im „Fortsetzen von Konversationen"-Leitfaden dokumentiert.

Die CLI in einem Browser ausführen, wenn Sie es brauchen

openhands web startet eine webzugängliche CLI (Standardport 12000).

openhands web

Wenn Sie lokal laufen, ist das Binden nur an localhost ein sinnvoller Standard:

openhands web --host 127.0.0.1 --port 12000

OpenHands warnt, dass das Offenlegen der Web-Schnittstelle für das Netzwerk geeignete Sicherheitsmaßnahmen erfordert, da sie vollen Zugang zu OpenHands-Fähigkeiten bietet.

Sicherheit, Fehlerbehebung und scharfe Kanten

Der wichtigste Sicherheitshebel in der OpenHands-CLI sind Genehmigungen:

• Die interaktive CLI kann vor sensiblen Aktionen nach einer Bestätigung fragen, und Sie können Bestätigungseinstellungen in der Sitzung konfigurieren.
• --always-approve entfernt Reibung, entfernt aber auch Sicherungen.
• --llm-approve fügt einen LLM-basierten Analysator für Genehmigungen hinzu.
• Der Headless-Modus genehmigt immer, also reservieren Sie ihn für Automatisierung in kontrollierten Umgebungen.

Wenn Sie mit lokalem Code arbeiten, bevorzugen Sie explizite Zugriffs Muster mit geringsten Privilegien:

• Für den GUI-Server mountet openhands serve --mount-cwd Ihr aktuelles Verzeichnis auf /workspace, sodass der Agent Ihre Projektdateien lesen und bearbeiten kann.
• Für Docker-basierte CLI-Läufe verwenden Sie SANDBOX_VOLUMES, um genau zu definieren, auf welche Verzeichnisse OpenHands zugreifen kann.

Wenn Sie ältere OpenHands-Zustandsverzeichnisse haben, bemerkt OpenHands einen Migrationspfad von ~/.openhands-state zu ~/.openhands in den lokalen Setup-Dokumenten und der Fehlerbeleitungsanleitung.

Schließlich, wenn Sie OpenHands in Skripte integrieren, sind Exit-Codes dokumentiert als:

• 0 Erfolg
• 1 Fehler oder Aufgabe fehlgeschlagen
• 2 ungültige Argumente

Meine Erfahrung mit OpenHands

Für mich hat OpenHands gut funktioniert, aber nicht immer… Ich habe versucht, es mit Devstral-Small-2, das auf Ollama gehostet wird, zum Laufen zu bringen, und es hat ständig aufgehört.

.

Obwohl OpenHands gut mit lokal gehostetem llama.cpp Qwen 3.5 35b funktioniert hat. Bisher ist für mich OpenCode so viel zuverlässiger.