OpenHands-CLI-Einführung: Installation, Flags, Headless-Modus

OpenHands ist ein Open-Source-Coding-Agent, der Dateien bearbeitet und Befehle in einer Sandbox ausführt. Dieser CLI-Schnellstart wurde am 26.10.2026 anhand des Pakets 1.16.0 überprüft.

Das Paket auf PyPI ist openhands 1.16.0, hochgeladen am 8. Mai 2026 und festgelegt auf openhands-sdk==1.21.0. Das README mit diesem Tag erfordert Python 3.12 und uv 0.11.6 oder neuer. Das README des Standard-Zweigs von OpenHands-CLI besagt, dass dieses Repository nicht mehr aktiv gepflegt wird und neue Installationen zu Agent Canvas weiterleitet. Der Headless-Modus und openhands acp sind weiterhin Teil des Befehlssets von 1.16.0.

Der Guide zu KI-Entwicklungstools folgt den anderen Terminal-Agenten auf dieser Website. Diese Seite behandelt die OpenHands-CLI: Installation, Einstellungsdateien, lokale Modell-URLs und die Flags, die ein Skript tatsächlich übergeben wird.

Was die CLI ist

Ein KI-Coding-Assistent generiert oder bearbeitet typischerweise Code aus einem Prompt. OpenHands erweitert dies zu einer Agenten-Schleife: planen, eine Aktion wie das Schreiben einer Datei oder das Ausführen eines Tests durchführen, das Ergebnis beobachten und fortsetzen. Das Projekt hieß zuvor OpenDevin. Die OpenHands-Paper beschreibt eine docker-basierte Laufzeitumgebung mit Shell- und Browserzugriff, was das Ausführungsmodell ist, das die CLI weiterhin kapselt.

Die Version 1.16.0 dokumentiert fünf Arten, diese Schleife auszuführen.

Agent Canvas, die von dem Projekt aktuell dokumentierte Installation

Am 3. Juni 2026 setzte die OpenHands-FAQ die Terminal-UI in einen Wartungsmodus bis zum 1. Oktober 2026 und erklärte, dass der Headless-Modus und ACP vollständig unterstützt bleiben. Die lokale GUI (openhands serve) sollte im Wartungsmodus bleiben, bis Agent Canvas isolierte, ephemere Sandboxes ausführen konnte. Diese FAQ definiert Wartung als Abhängigkeitsupdates, kritische Fehlerbehebungen und neue LLMs. Das Haupt-Repository von OpenHands veröffentlichte Agent Canvas 1.33.0 am 23. Oktober 2026.

agent-canvas startet die aktuelle UI und deren Backend. openhands serve startet die Legacy-GUI und startet Agent Canvas nicht.

Agent Canvas benötigt Node.js 24 oder neuer und uv. Erster Start ohne globale Installation:

npx @openhands/agent-canvas

Der Prozess lauscht auf http://localhost:8000. Das Schließen dieses Terminals stoppt das lokale Backend. Eine globale Installation erfolgt über npm install -g @openhands/agent-canvas, danach agent-canvas. Der npm-Pfad führt den Agent-Server als Ihr Benutzer aus, sodass der Agent mit den Berechtigungen Ihres Kontos auf lokale Dateien zugreifen kann.

Der Docker-Pfad veröffentlicht den Port nur auf localhost und mountet ein Projektverzeichnis:

mkdir -p ~/projects

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -v openhands-data:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

Der Container liefert die UI unter http://localhost:8000/canvas. Der benannte Volume openhands-data bewahrt die Einstellungen nach --rm auf. Auf Linux schlägt das Bind-Mounten von ~/.openhands in dieses Image mit unable to open database file fehl: Der Container-Benutzer ist UID 10001, und ein Host-Verzeichnis ist normalerweise Ihrem eigenen UID zugeordnet. Die Installationsseite verwendet aus diesem Grund das benannte Volume. Bereits in ~/.openhands vorhandene Einstellungen werden nicht in ein neues Volume kopiert.

Installation der OpenHands-CLI

Verwenden Sie die CLI, wenn Sie weiterhin openhands --headless oder openhands acp wünschen. Das veröffentlichte Rad wird nur auf Python 3.12 installiert (==3.12.* auf PyPI). uv muss 0.11.6 oder neuer sein. Auf Windows sagt die Installationsseite, die Befehle in WSL (Ubuntu) auszuführen.

Installation mit uv

uv tool install openhands --python 3.12
openhands

Upgraden mit derselben Interpreter-Festlegung:

uv tool upgrade openhands --python 3.12

Die lokale Setup-Seite sagt, dass uv die CLI vom Projekt-Virtualenv isoliert und dass die standardmäßigen MCP-Server dies erfordern.

Installation der Standalone-Binary

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

Auf macOS kann ein Gatekeeper-Dialog die Binary blockieren („openhands kann nicht geöffnet werden, da Apple sie nicht auf schädliche Software prüfen kann“). Der Pfad auf der Installationsseite ist Systemeinstellungen, Datenschutz & Sicherheit, dann „Trotzdem erlauben“ unter Sicherheit, danach openhands erneut ausführen.

CLI über Docker ausführen

Der Container auf der Installationsseite setzt AGENT_SERVER_IMAGE_TAG auf das agent-server-Image. Das uv tool install openhands im Inneren des Containers ist die PyPI-CLI. Der Tag in diesem Beispiel, für diese Seite überprüft, ist 1.26.0-python. Ältere Kopien dieses Befehls verwendeten 1.12.0-python.

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.26.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"

SANDBOX_USER_ID=$(id -u) stellt sicher, dass der Sandbox-Benutzer dem Host-Benutzer entspricht, damit der Agent keine root-gesicherten Dateien im gemounteten Workspace hinterlässt. SANDBOX_VOLUMES ist das Verzeichnis, auf das der Agent zugreifen darf.

OPENHANDS_VERSION wählt die Docker-Image-Version für openhands serve. Sie ändert nicht die PyPI-CLI-Version.

Einstellungsdateien

Beim ersten Start fragt die CLI nach den Model-Einstellungen und schreibt diese unter ~/.openhands/. Das README von 1.16.0 und die Befehlsreferenz benennen diese Dateien:

Die Installationsseite sagt Docker-Benutzern nach wie vor, ~/.openhands/settings.json vorzubereiten. Das CLI-README und AgentStore im Baum von 1.16.0 persistieren die Agenten-Spezifikation in agent_settings.json. Eine CLI-Installation, die den Dateinamen der Installationsseite übersprang und agent_settings.json schrieb, entspricht dieser Quelle.

create_and_save_from_settings baut zwei LLM-Objekte aus demselben Modell, API-Schlüssel und Basis-URL: eines für den Agenten und eines für den zusammenfassenden Kondensator. Daher wiederholt eine gespeicherte Datei die llm-Felder. Bearbeiten Sie die Agentendatei mit einem beliebigen Editor:

nano ~/.openhands/agent_settings.json

LLM_API_KEY, LLM_MODEL und LLM_BASE_URL werden ignoriert, es sei denn, Sie entscheiden sich dafür. Das Überschreiben wird nicht gespeichert:

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

OPENHANDS_CLOUD_URL setzt den Standard-Cloud-Server. Die Befehle cloud und login verwenden standardmäßig https://app.all-hands.dev, wenn diese Variable nicht gesetzt ist.

Upgrades von einer CLI älter als 1.0.0 erfordern, dass die Einstellungen erneut eingegeben werden. Die Installationsseite besagt, dass das Konfigurationsformat bei 1.0.0 geändert wurde.

Lokale Modelle

Der Local-LLM-Guide vom 21. Mai 2026 empfiehlt Qwen3.6-35B-A3B als erstes lokales Modell zum Ausprobieren. Er erfordert eine GPU mit mindestens 24GB VRAM für ein quantisiertes Build oder einen Apple-Silicon-Mac mit mindestens 64GB Unified Memory. Dieselbe Seite sagt, die Kontextlänge auf mindestens 22000 Tokens zu setzen, und dass Ollamas Standard von 4096 für den System-Prompt zu klein ist.

Wenn der Agent niemals Tools aufruft, behandelt der Guide dies als Modellgrenze und nennt Community-Berichte für qwen2.5-coder-14b-instruct und qwopus3.5-27b-v3. Die Vergleichstabelle für lokalen Hosting-Dienst ist die server-spezifische Tabelle, wenn Ollama, vLLM, LM Studio oder LocalAI noch eine offene Option ist.

Ollama

Das Ollama-Startkommando des Guides setzt die Kontextlänge vor ollama serve. Der Ollama CLI Spickzettel behandelt serve, run und ps neben dieser Variable.

OLLAMA_CONTEXT_LENGTH=32768 OLLAMA_HOST=0.0.0.0:11434 OLLAMA_KEEP_ALIVE=-1 ollama serve
ollama pull qwen3.6:35b-a3b

Für OpenHands, die in Docker läuft, sind die Einstellungen des Guides: Custom Modell openai/qwen3.6:35b-a3b, Basis-URL http://host.docker.internal:11434/v1 und jeder Platzhalter-API-Schlüssel. Eine CLI, die auf demselben Host wie Ollama läuft, verwendet stattdessen http://127.0.0.1:11434/v1 anstelle von host.docker.internal. Linux LM Studio und andere nur Loopback-fähige Server sind aus einem Container heraus nicht über 127.0.0.1 erreichbar; die Prüfung des Guides besteht darin, das Servicing im lokalen Netzwerk zu aktivieren und host.docker.internal aus dem Inneren des Containers zu testen.

Die Terminal-Seite öffnet diesen Bildschirm mit Ctrl+P, dann Einstellungen. Ein gespeichertes CLI-Profil verwendete eine ollama/-Modell-ID und eine Basis-URL ohne /v1:

• Custom Modell: ollama/devstral-small-2:24b
• Basis-URL: http://localhost:11434

Diese Devstral-Small-2-Sitzung ist diejenige, die immer wieder aufhörte. Die für sie eingetragenen Felder, sowohl im Agenten-LLM als auch im Kondensator-LLM, waren:

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

llama.cpp und vLLM

llama.cpp verwendete das OpenAI-kompatible Präfix und eine /v1-Basis-URL, ebenfalls in beiden LLM-Objekten:

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

Der Server-Befehl, mit Flags, die im llama.cpp-Schnellstart behandelt werden, war:

./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

Gegenüber diesem Server beendete die CLI einen Go IndexNow-Client: Quelle, ein ausführbares File und ein README. Der Task-Text war create for me a cli tool in Go, that would call bing and other search engines' indexnow endpoints to notify about changes on my website.

Das vLLM-Beispiel des Local-LLM-Guides für das neuere Qwen3.6-Modell ist ein Serve auf zwei GPUs. Der vLLM-Schnellstart behandelt die Flags von vllm serve und Speicherüberlauf-Prüfungen. Die entsprechende OpenHands-Modellzeichenfolge des Guides ist openai/Qwen3.6-35B-A3B, mit Basis-URL http://host.docker.internal:8000/v1 und demselben --api-key, mit dem der Server gestartet wurde (mykey in ihrem Beispiel).

vllm serve Qwen/Qwen3.6-35B-A3B \
    --host 0.0.0.0 --port 8000 \
    --api-key mykey \
    --tensor-parallel-size 2 \
    --served-model-name Qwen3.6-35B-A3B \
    --enable-prefix-caching

Interaktive Steuerung

openhands ohne Unterbefehl öffnet die Terminal-UI. Die Terminal-Seite listet diese Steuerungen auf:

Slash-Befehle aus der Befehlsreferenz: /help, /new, /history, /confirm, /condense, /skills, /feedback, /exit. Modellwechsel über den Settings-Eintrag der Palette werden ohne Neustart angewendet. --exit-without-confirmation überspringt den Beendigungsdialog. --exp wählt die textuelle UI und ist als Kompatibilitäts-Flag dokumentiert, da diese UI bereits der Standard ist.

Flags und Unterbefehle

openhands [OPTIONS] [COMMAND]

Globale Optionen in der Befehlsreferenz, geprüft gegen argparsers/util.py auf dem 1.16.0-Tag für die Freigabe- und Umgebungs-Flags:

--always-approve und --llm-approve können nicht kombiniert werden. Der Standard-Interaktionsmodus fragt vor Aktionen.

Unterbefehle, die zum Einsatz kommen, wenn die TUI nicht ausreicht:

• openhands serve startet die Legacy-GUI in Docker. --mount-cwd mountet das aktuelle Verzeichnis unter /workspace. --gpu schaltet nvidia-docker ein.
• openhands web bedient die CLI im Browser. --host standardmäßig 0.0.0.0, --port standardmäßig 12000, --debug ist aus.
• openhands acp spricht Agent Client Protocol über stdio. Flags: --resume, --last, --always-approve, --llm-approve, --streaming.
• openhands cloud -t "task" öffnet ein Cloud-Gespräch. --server-url überschreibt https://app.all-hands.dev.
• openhands login und openhands logout verwalten dieses Cloud-Konto. logout ohne --server-url meldet sich bei jedem gespeicherten Server ab.
• openhands mcp verwaltet Server: add, list, get, remove, enable, disable. add erfordert --transport von http, sse oder stdio.

Ein MCP-Server aus dem README von 1.16.0:

openhands mcp list
openhands mcp add tavily --transport stdio \
  npx -- -y mcp-remote "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>"
openhands mcp enable tavily
openhands mcp disable tavily

Beispiele

Interaktive Aufgabe

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

Aufgaben-Datei

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

openhands -f task.txt

Headless, einschließlich JSONL

Der Headless-Modus erfordert --task oder --file. Er läuft immer im always-approve-Modus, und --llm-approve wird dort abgelehnt. Behandeln Sie das Arbeitsverzeichnis so, als könnte der Agent es frei modifizieren.

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

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

Die Headless-Seite beschreibt --json als ein JSON-Objekt pro Event, gestreamt als JSONL.

Fortsetzen

openhands --resume
openhands --resume --last
openhands --resume abc123def456

Browser-TUI, gebunden an localhost

openhands web ist standardmäßig auf 0.0.0.0:12000 gebunden, was aus dem Netzwerk erreichbar ist. Die CLI-Dokumente sagen, dass dieses Interface die volle Fähigkeit der CLI hat, daher ist eine nur-lokale Bindung die sicherere Standardvorgabe:

openhands web --host 127.0.0.1 --port 12000

ACP für einen Editor

Die ACP-Clients der IDE-Seite sind Zed und JetBrains (nativ), Toad (nativ) und VS Code (Community-Erweiterung). Der Editor startet openhands acp und kommuniziert über stdio mit JSON-RPC 2.0, wobei die gespeicherten LLM-Einstellungen der CLI verwendet werden.

openhands acp
openhands acp --llm-approve
openhands acp --resume --last

Freigabe, Exit-Codes und Ergebnisse lokaler Modelle

Interaktive Sitzungen fragen vor Aktionen. /confirm ändert diese Richtlinie in der Sitzung. --always-approve (Alias --yolo) genehmigt alles. --llm-approve fragt nur nach für Aktionen, die der Sicherheitsanalysator als hohes Risiko bewertet. Der Headless-Modus ist immer-approve für den gesamten Lauf.

openhands serve --mount-cwd mountet das aktuelle Verzeichnis unter /workspace im Inneren des Legacy-GUI-Containers. Der Docker-CLI-Flow verwendet SANDBOX_VOLUMES für dieselbe Grenze.

Exit-Codes in der Befehlsreferenz:

Devstral-Small-2 24B auf Ollama hat in dieser CLI immer wieder gestoppt.

Die oben erwähnte llama.cpp-Sitzung, Qwen3.5-35B-A3B mit einem 70000-Token-Kontext, hat die IndexNow-Aufgabe abgeschlossen. Für einen Terminal-Agenten, der auf derselben Maschine weiterarbeitete, ist der OpenCode-Schnellstart die Installation und das Provider-Setup.