# OpenHands KI-Entwickler

## Überblick

[OpenHands](https://github.com/All-Hands-AI/OpenHands) (früher OpenDevin) ist eine Open-Source-Plattform für autonome KI-Software-Entwicklungsagenten. Mit über 65.000 GitHub-Sternen ist sie zu einem der beliebtesten Werkzeuge geworden, um reale Programmieraufgaben an KI zu delegieren — Code schreiben, Fehler beheben, GitHub-Issues lösen, Shell-Befehle ausführen, im Web browsen und mit Ihrem Codebestand von Anfang bis Ende interagieren.

Im Gegensatz zu typischen Code-Vervollständigungswerkzeugen läuft OpenHands in einer **agentischen Schleife**: es erhält eine Aufgabe, plant, schreibt Code, führt ihn aus, beobachtet die Ausgabe und iteriert — alles ohne menschliches Eingreifen. Es unterstützt Dutzende von LLM-Backends einschließlich OpenAI, Anthropic Claude, Google Gemini sowie lokal gehostete Modelle über Ollama oder vLLM.

**Warum Clore.ai für OpenHands?**

* OpenHands selbst ist CPU-basiert und benötigt keine GPU
* Die Kombination mit einem **lokalen LLM** (Ollama, vLLM) auf demselben Server eliminiert API-Kosten und Latenz
* Clore.ais erschwingliche GPU-Server ermöglichen es Ihnen, sowohl OpenHands als auch ein lokales Modell für nur **0,20–0,35 $/Std.**
* Sie erhalten persistenten Workspace-Speicher, Docker-in-Docker-Unterstützung und vollständigen Root-Zugriff
* Ideal für lang laufende autonome Aufgaben, die über Cloud-LLM-APIs teuer wären

**Typische Anwendungsfälle auf Clore.ai:**

* Autonome Code-Generierung aus einer Spezifikation oder Issue-Beschreibung
* Massenrefactoring großer Codebasen
* Ausführen von OpenHands + Ollama zusammen für 100% offline agentische Entwicklung
* CI/CD-Task-Automatisierung ohne API-Kosten

***

## Anforderungen

OpenHands benötigt Zugriff auf den Docker-Socket und führt intern einen sandboxed Runtime-Container aus. Die folgende Tabelle behandelt empfohlene Konfigurationen auf Clore.ai:

| Konfiguration                   | GPU                | VRAM  | RAM   | Speicher | Geschätzter Preis  |
| ------------------------------- | ------------------ | ----- | ----- | -------- | ------------------ |
| **Nur API (kein lokales LLM)**  | Beliebig / nur CPU | N/A   | 8 GB  | 20 GB    | \~0,05–0,10 $/Std. |
| **+ Ollama (Llama 3.1 8B)**     | RTX 3090           | 24 GB | 16 GB | 40 GB    | \~$0.20/Stunde     |
| **+ Ollama (Qwen2.5 32B)**      | RTX 4090           | 24 GB | 32 GB | 60 GB    | \~$0.35/Stunde     |
| **+ vLLM (Llama 3.1 70B)**      | A100 80GB          | 80 GB | 64 GB | 100 GB   | \~$1.10/Stunde     |
| **+ vLLM (Llama 3.3 70B INT4)** | RTX 4090           | 24 GB | 32 GB | 80 GB    | \~$0.35/Stunde     |

> **Hinweis:** Wenn Sie nur OpenAI/Anthropic/Gemini-APIs verwenden, funktioniert jeder Server mit ≥8 GB RAM. Eine GPU ist nur erforderlich, wenn Sie ein lokales LLM auf derselben Maschine betreiben möchten. Siehe die [GPU-Vergleichsanleitung](https://docs.clore.ai/guides/guides_v2-de/erste-schritte/gpu-comparison) für weitere Details.

**Softwareanforderungen auf dem Clore.ai-Server:**

* Docker Engine (auf allen Clore.ai-Images vorinstalliert)
* NVIDIA Container Toolkit (vorinstalliert auf GPU-Images)
* Docker-Socket zugänglich unter `/var/run/docker.sock`
* Ausgehender Internetzugang zum Herunterladen von GHCR-Images

***

## Schnellstart

### Schritt 1: Wählen und verbinden Sie sich mit einem Clore.ai-Server

Im [Clore.ai-Marktplatz](https://clore.ai), filtern Sie Server nach:

* RAM ≥ 16 GB (für lokale LLM-Kombination)
* Docker: ✓ aktiviert
* Wählen Sie Ihre bevorzugte GPU, wenn Sie ein lokales Modell verwenden

Verbinden Sie sich per SSH, sobald der Server bereitgestellt wurde:

```bash
ssh root@<server-ip> -p <port>
```

### Schritt 2: Überprüfen Sie, ob Docker läuft

```bash
docker info
ls -la /var/run/docker.sock
```

Beide Befehle sollten erfolgreich sein. Wenn der Docker-Socket fehlt, kontaktieren Sie den Clore.ai-Support oder wählen Sie ein anderes Image.

### Schritt 3: OpenHands ziehen und starten

```bash
# Workspace-Verzeichnis setzen
export WORKSPACE_BASE=$(pwd)/workspace
mkdir -p $WORKSPACE_BASE

# OpenHands ausführen (zieht das neueste 0.38-Image von GHCR)
docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

### Schritt 4: Zugriff auf die Web-UI

Die UI ist verfügbar unter `http://<server-ip>:3000`

> **Clore.ai Portweiterleitung:** Stellen Sie im Clore.ai-Dashboard sicher, dass der Port `3000` in Ihrer Serverkonfiguration weitergeleitet/offengelegt ist. Manche Vorlagen beschränken externe Ports — prüfen Sie den Bereich „Ports“ in Ihren Serverdetails.

Beim ersten Start wird OpenHands Sie auffordern, einen LLM-Anbieter zu konfigurieren.

### Schritt 5: Konfigurieren Sie Ihr LLM

In den Einstellungen der Web-UI:

* **Anbieter:** Wählen Sie OpenAI, Anthropic, Google oder Benutzerdefiniert
* **API-Schlüssel:** Geben Sie Ihren API-Schlüssel ein
* **Modell:** z. B. `gpt-4o`, `claude-3-5-sonnet-20241022`, oder `ollama/llama3.1`

Für lokales Ollama (siehe Abschnitt GPU-Beschleunigung unten) verwenden Sie:

* Anbieter: `ollama`
* Basis-URL: `http://host.docker.internal:11434`
* Modell: `ollama/llama3.1:8b`

***

## Konfiguration

### Umgebungsvariablen

OpenHands kann vollständig über Umgebungsvariablen konfiguriert werden, die an `docker run`:

```bash
docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 \
  -e LLM_API_KEY=sk-ant-... \
  -e LLM_BASE_URL="" \
  -e SANDBOX_TIMEOUT=120 \
  -e MAX_ITERATIONS=100 \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

| Variable          | Beschreibung                                                          | Standard          |
| ----------------- | --------------------------------------------------------------------- | ----------------- |
| `LLM_MODEL`       | Modellkennzeichen (z. B. `gpt-4o`, `claude-3-5-sonnet-20241022`)      | Im UI gesetzt     |
| `LLM_API_KEY`     | API-Schlüssel für den LLM-Anbieter                                    | Im UI gesetzt     |
| `LLM_BASE_URL`    | Benutzerdefinierte Basis-URL (für Ollama, vLLM, LiteLLM)              | Anbieter-Standard |
| `SANDBOX_TIMEOUT` | Sandbox-Timeout des Agenten in Sekunden                               | `120`             |
| `MAX_ITERATIONS`  | Maximale agentische Schleifen-Iterationen pro Aufgabe                 | `100`             |
| `SANDBOX_USER_ID` | UID, unter der die Sandbox ausgeführt wird (verwenden Sie `$(id -u)`) | `0`               |
| `LOG_ALL_EVENTS`  | Aktivieren Sie ausführliche Ereignisprotokollierung (`true`/`false`)  | `false`           |

### Persistente Konfigurationsdatei

Sie können Einstellungen beibehalten, indem Sie ein Konfigurationsverzeichnis mounten:

```bash
mkdir -p /opt/openhands/config

docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/openhands/config:/app/config \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

### Im Hintergrund ausführen (Detached-Modus)

Für lang laufende Sitzungen auf Clore.ai:

```bash
export WORKSPACE_BASE=/opt/workspace
mkdir -p $WORKSPACE_BASE

docker run -d \
  --name openhands \
  --restart unless-stopped \
  --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 \
  -e LLM_API_KEY=your_api_key_here \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38

# Logs anzeigen
docker logs -f openhands
```

***

## GPU-Beschleunigung (Integration lokaler LLMs)

Auch wenn OpenHands selbst die GPU nicht nutzt, verschafft die Kombination mit einem **lokalen LLM** auf Clore.ais GPU laufenden Modell Ihnen einen leistungsstarken, kosteneffizienten, API-freien autonomen Agenten.

### Option A: OpenHands + Ollama (Empfohlen für Einsteiger)

Starten Sie zuerst Ollama und richten Sie dann OpenHands darauf ein:

```bash
# 1. Ollama starten (siehe Ollama-Anleitung für vollständige Details)
docker run -d \
  --name ollama \
  --gpus all \
  -p 11434:11434 \
  -v ollama-data:/root/.ollama \
  ollama/ollama:latest

# 2. Ein für Coding optimiertes Modell ziehen
docker exec ollama ollama pull qwen2.5-coder:7b
# Oder für mehr Leistung:
docker exec ollama ollama pull llama3.1:8b
docker exec ollama ollama pull deepseek-coder-v2:16b

# 3. OpenHands starten und auf Ollama verweisen
export WORKSPACE_BASE=/opt/workspace
mkdir -p $WORKSPACE_BASE

docker run -d \
  --name openhands \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=ollama/qwen2.5-coder:7b \
  -e LLM_BASE_URL=http://host.docker.internal:11434 \
  -e LLM_API_KEY=ollama \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

> Siehe das vollständige [Ollama-Anleitung](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/ollama) für Modellauswahl, Performance-Tuning und GPU-Konfiguration.

### Option B: OpenHands + vLLM (Hohe Leistung)

Für maximale Durchsatzleistung mit größeren Modellen:

```bash
# 1. vLLM mit einem Coding-Modell starten
docker run -d \
  --name vllm \
  --gpus all \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --max-model-len 16384 \
  --gpu-memory-utilization 0.92

# Warten Sie, bis das Modell geladen ist (~2–5 Min.)
docker logs -f vllm | grep "Application startup"

# 2. OpenHands mit vLLM-Backend starten
docker run -d \
  --name openhands \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=/opt/workspace \
  -e LLM_MODEL=openai/Qwen/Qwen2.5-Coder-32B-Instruct \
  -e LLM_BASE_URL=http://host.docker.internal:8000/v1 \
  -e LLM_API_KEY=none \
  -v /opt/workspace:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

> Siehe die [vLLM-Anleitung](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/vllm) für die vollständige Einrichtung, Quantisierungsoptionen und Multi-GPU-Konfigurationen.

### Empfohlene lokale Modelle fürs Codieren

| Modell                  | Größe | Min. VRAM | Qualität |
| ----------------------- | ----- | --------- | -------- |
| `qwen2.5-coder:7b`      | 7B    | 8 GB      | ★★★☆☆    |
| `deepseek-coder-v2:16b` | 16B   | 12 GB     | ★★★★☆    |
| `qwen2.5-coder:32b`     | 32B   | 24 GB     | ★★★★☆    |
| `llama3.1:70b`          | 70B   | 48 GB     | ★★★★★    |

***

## Tipps & bewährte Methoden

### 1. Workspace-Mounts sinnvoll nutzen

Moun-ten Sie Ihr tatsächliches Projektverzeichnis als Workspace, damit OpenHands Ihre Dateien direkt bearbeiten kann:

```bash
export WORKSPACE_BASE=/opt/my-project
git clone https://github.com/your/repo $WORKSPACE_BASE
```

### 2. Aufgaben-Prompting für beste Ergebnisse

OpenHands arbeitet am besten mit spezifischen, umsetzbaren Prompts:

```
✅ Gut: „Behebe den Authentifizierungsfehler in src/auth/login.py, bei dem JWT-Tokens 
         sofort ablaufen. Das Problem liegt in der Berechnung der Token-Ablaufzeit.“

❌ Schlecht: „Behebe den Fehler“
```

### 3. Ressourcenverbrauch überwachen

```bash
# GPU- und Speichernutzung beobachten
watch -n 2 'nvidia-smi && docker stats --no-stream'
```

### 4. Iterationslimits setzen

Verhindern Sie, dass außer Kontrolle geratene Agenten zu viele API-Tokens verbrauchen:

```bash
-e MAX_ITERATIONS=50  # Auf 50 Schritte pro Aufgabe begrenzen
```

### 5. GitHub-Integration

OpenHands kann GitHub-Issues direkt lösen. Konfigurieren Sie es in der UI:

* GitHub-Token: Ihr persönlicher Zugriffstoken mit `repo` Berechtigung
* OpenHands wird das Repo klonen, das Problem beheben und einen PR erstellen

### 6. Kostenschätzung

Für API-basierte LLMs schätzen Sie die Kosten pro Aufgabe:

* Einfacher Bugfix: \~0,05–0,15 $ (Claude Haiku/GPT-4o-mini)
* Komplexes Feature: \~0,50–2,00 $ (Claude Sonnet/GPT-4o)
* Ab 100+ Aufgaben/Tag zahlt sich ein lokales LLM auf Clore.ai aus

***

## Fehlerbehebung

### Docker-Socket: Berechtigung verweigert

```bash
# Fehler: Zugriff verweigert beim Verbinden mit dem Docker-Daemon
# Fehlerbehebung: Stellen Sie sicher, dass der Socket zugänglich ist
ls -la /var/run/docker.sock
# Sollte anzeigen: srw-rw---- 1 root docker ...

# Fügen Sie ggf. Ihren Benutzer zur docker-Gruppe hinzu
usermod -aG docker $USER
# Starten Sie dann die Shell neu oder verwenden Sie: newgrp docker
```

### Sandbox-Container startet nicht

```bash
# Prüfen Sie, ob das Runtime-Image zugänglich ist
docker pull ghcr.io/all-hands-ai/runtime:0.38-nikolaik

# Prüfen Sie GHCR-Rate-Limits (ggf. Authentifizierung erforderlich)
docker login ghcr.io
```

### Port 3000 nicht zugänglich

```bash
# Überprüfen Sie, ob der Container läuft und der Port gebunden ist
docker ps | grep openhands
docker port openhands

# Prüfen Sie die Clore.ai-Firewall — stellen Sie sicher, dass Port 3000 in Ihrer Portzuordnung ist
# Im Clore.ai-Dashboard: Server → Ports → 3000:3000 hinzufügen
```

### LLM-Verbindungsfehler mit Ollama

```bash
# Testen Sie, ob Ollama vom OpenHands-Container erreichbar ist
docker exec openhands curl http://host.docker.internal:11434/api/tags

# Wenn es fehlschlägt, prüfen Sie, ob das --add-host-Flag im docker run enthalten war
# Prüfen Sie außerdem, ob der Ollama-Container läuft:
docker ps | grep ollama
docker logs ollama | tail -20
```

### Agenten-Schleifen laufen unendlich

```bash
# Reduzieren Sie die max. Iterationen
docker stop openhands
docker run ... -e MAX_ITERATIONS=30 ...

# Oder setzen Sie ein Timeout
-e SANDBOX_TIMEOUT=60
```

### Out of Memory (OOM)

```bash
# Speicherverbrauch prüfen
free -h
docker stats

# Wenn Sie ein lokales LLM betreiben, versuchen Sie ein kleineres Modell
docker exec ollama ollama pull qwen2.5-coder:3b

# Oder verwenden Sie eine quantisierte Version (weniger VRAM)
docker exec ollama ollama pull llama3.1:8b-instruct-q4_K_M
```

***

## Weiterführende Lektüre

* [OpenHands GitHub-Repository](https://github.com/All-Hands-AI/OpenHands) — Quellcode, Issues und Releases
* [OpenHands-Dokumentation](https://docs.all-hands.dev) — Offizielle Dokumentation einschließlich LLM-Konfiguration
* [Ollama auf Clore.ai](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/ollama) — Lokale LLMs für kostenlose Agenten-Inferenz betreiben
* [vLLM auf Clore.ai](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/vllm) — Hochleistungsfähiges lokales LLM-Serving
* [GPU-Vergleichsanleitung](https://docs.clore.ai/guides/guides_v2-de/erste-schritte/gpu-comparison) — Wählen Sie die richtige GPU für Ihre Arbeitslast
* [OpenHands Discord](https://discord.gg/ESHStjSjD4) — Community-Support und Modell-Empfehlungen
* [SWE-bench Bestenliste](https://www.swebench.com) — Vergleichen Sie die Agentenleistung an realen GitHub-Issues