> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-fr/plateformes-et-agents-ia/openhands.md).

# OpenHands AI Developer

## Aperçu

[OpenHands](https://github.com/All-Hands-AI/OpenHands) (anciennement OpenDevin) est une plateforme open-source pour des agents de développement logiciel autonomes alimentés par l'IA. Avec plus de 65K étoiles sur GitHub, elle est devenue l'un des outils les plus populaires pour déléguer de vraies tâches de programmation à l'IA — écrire du code, corriger des bugs, résoudre des issues GitHub, exécuter des commandes shell, parcourir le web et interagir avec votre base de code de bout en bout.

Contrairement aux outils classiques d'auto-complétion de code, OpenHands exécute une **boucle agentique**: elle reçoit une tâche, planifie, écrit du code, l'exécute, observe la sortie et itère — le tout sans intervention humaine. Elle prend en charge des dizaines de backends LLM, notamment OpenAI, Anthropic Claude, Google Gemini, et des modèles hébergés localement via Ollama ou vLLM.

**Pourquoi Clore.ai pour OpenHands ?**

* OpenHands lui-même est basé sur le CPU et ne nécessite pas de GPU
* Cependant, l'associer à un **LLM local** (Ollama, vLLM) sur le même serveur élimine les coûts et la latence des API
* Les serveurs GPU abordables de Clore.ai vous permettent d'exécuter à la fois OpenHands et un modèle local pour aussi peu que **0,20 $–0,35 $/h**
* Vous bénéficiez d'un stockage de workspace persistant, du support Docker-in-Docker et d'un accès root complet
* Idéal pour des tâches autonomes de longue durée qui seraient coûteuses via les API LLM cloud

**Cas d'utilisation typiques sur Clore.ai :**

* Génération de code autonome à partir d'un cahier des charges ou de la description d'une issue
* Refactorisation en masse de grandes bases de code
* Exécution conjointe d'OpenHands + Ollama pour un développement agentique 100 % hors ligne
* Automatisation des tâches CI/CD sans coûts d'API

***

## Exigences

OpenHands nécessite l'accès au socket Docker et exécute un conteneur runtime sandboxé en interne. Le tableau suivant couvre les configurations recommandées sur Clore.ai :

| Configuration                         | GPU                               | VRAM  | RAM   | Stockage | Prix estimé     |
| ------------------------------------- | --------------------------------- | ----- | ----- | -------- | --------------- |
| **API uniquement (pas de LLM local)** | N'importe lequel / CPU uniquement | N/A   | 8 Go  | 20 Go    | \~0,05–0,10 $/h |
| **+ Ollama (Llama 3.1 8B)**           | RTX 3090                          | 24 Go | 16 Go | 40 Go    | \~0,20 $/h      |
| **+ Ollama (Qwen2.5 32B)**            | RTX 4090                          | 24 Go | 32 Go | 60 Go    | \~0,35 $/h      |
| **+ vLLM (Llama 3.1 70B)**            | A100 80GB                         | 80 Go | 64 Go | 100 Go   | \~1,10 $/h      |
| **+ vLLM (Llama 3.3 70B INT4)**       | RTX 4090                          | 24 Go | 32 Go | 80 Go    | \~0,35 $/h      |

> **Remarque :** Si vous utilisez uniquement les APIs OpenAI/Anthropic/Gemini, tout serveur avec ≥8 Go de RAM convient. Le GPU n'est nécessaire que si vous souhaitez exécuter un LLM local sur la même machine. Voir le [Guide de comparaison GPU](/guides/guides_v2-fr/prise-en-main/gpu-comparison.md) pour plus de détails.

**Exigences logicielles sur le serveur Clore.ai :**

* Docker Engine (pré-installé sur toutes les images Clore.ai)
* NVIDIA Container Toolkit (pré-installé sur les images GPU)
* Socket Docker accessible à `/var/run/docker.sock`
* Accès internet sortant pour récupérer des images GHCR

***

## Démarrage rapide

### Étape 1 : Sélectionnez et connectez-vous à un serveur Clore.ai

Dans le [la place de marché Clore.ai](https://clore.ai), filtrez les serveurs par :

* RAM ≥ 16 Go (pour la combinaison avec LLM local)
* Docker : ✓ activé
* Choisissez votre GPU préféré si vous utilisez un modèle local

Connectez-vous via SSH une fois le serveur provisionné :

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

### Étape 2 : Vérifiez que Docker est en cours d'exécution

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

Les deux commandes devraient réussir. Si le socket Docker est manquant, contactez le support Clore.ai ou choisissez une image différente.

### Étape 3 : Récupérer et exécuter OpenHands

```bash
# Définir le répertoire de workspace
export WORKSPACE_BASE=$(pwd)/workspace
mkdir -p $WORKSPACE_BASE

# Exécuter OpenHands (récupère la dernière image 0.38 depuis 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
```

### Étape 4 : Accéder à l'interface Web

L'interface est disponible à `http://<server-ip>:3000`

> **Redirection de port Clore.ai :** Dans le tableau de bord Clore.ai, assurez-vous que le port `3000` est redirigé/exposé dans la configuration de votre serveur. Certains templates restreignent les ports externes — vérifiez la section "Ports" dans les détails de votre serveur.

Au premier lancement, OpenHands vous demandera de configurer un fournisseur LLM.

### Étape 5 : Configurez votre LLM

Dans les paramètres de l'interface web :

* **Fournisseur :** Sélectionnez OpenAI, Anthropic, Google ou Personnalisé
* **Clé API :** Saisissez votre clé API
* **Modèle :** par ex., `gpt-4o`, `claude-3-5-sonnet-20241022`, ou `ollama/llama3.1`

Pour Ollama local (voir la section Accélération GPU ci‑dessous), utilisez :

* Fournisseur : `ollama`
* URL de base : `http://host.docker.internal:11434`
* Modèle : `ollama/llama3.1:8b`

***

## Configuration

### Variables d'environnement

OpenHands peut être entièrement configuré via des variables d'environnement passées à `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          | Description                                                          | Par défaut                |
| ----------------- | -------------------------------------------------------------------- | ------------------------- |
| `LLM_MODEL`       | Identifiant du modèle (p.ex. `gpt-4o`, `claude-3-5-sonnet-20241022`) | Défini dans l'UI          |
| `LLM_API_KEY`     | Clé API pour le fournisseur LLM                                      | Défini dans l'UI          |
| `LLM_BASE_URL`    | URL de base personnalisée (pour Ollama, vLLM, LiteLLM)               | Par défaut du fournisseur |
| `SANDBOX_TIMEOUT` | Timeout du sandbox de l'agent en secondes                            | `120`                     |
| `MAX_ITERATIONS`  | Nombre maximal d'itérations de la boucle agentique par tâche         | `100`                     |
| `SANDBOX_USER_ID` | UID pour exécuter le sandbox comme (utilisez `$(id -u)`)             | `0`                       |
| `LOG_ALL_EVENTS`  | Activer la journalisation détaillée des événements (`true`/`false`)  | `false`                   |

### Fichier de configuration persistant

Vous pouvez conserver les paramètres en montant un répertoire de configuration :

```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
```

### Exécution en arrière-plan (mode détaché)

Pour des sessions de longue durée sur 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

# Voir les logs
docker logs -f openhands
```

***

## Accélération GPU (Intégration LLM local)

Bien qu'OpenHands n'utilise pas le GPU lui-même, le combiner avec un **LLM local** exécuté sur le GPU de Clore.ai vous offre un agent autonome puissant, économique et sans API.

### Option A : OpenHands + Ollama (recommandé pour les débutants)

Démarrez Ollama en premier, puis pointez OpenHands vers celui-ci :

```bash
# 1. Démarrer Ollama (voir le guide Ollama pour tous les détails)
docker run -d \
  --name ollama \
  --gpus all \
  -p 11434:11434 \
  -v ollama-data:/root/.ollama \
  ollama/ollama:latest

# 2. Récupérer un modèle optimisé pour le codage
docker exec ollama ollama pull qwen2.5-coder:7b
# Ou pour plus de puissance :
docker exec ollama ollama pull llama3.1:8b
docker exec ollama ollama pull deepseek-coder-v2:16b

# 3. Démarrer OpenHands en le pointant vers Ollama
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
```

> Voir le guide complet [guide Ollama](/guides/guides_v2-fr/modeles-de-langage/ollama.md) pour la sélection de modèle, l'optimisation des performances et la configuration GPU.

### Option B : OpenHands + vLLM (Haute performance)

Pour un débit maximal avec des modèles plus grands :

```bash
# 1. Démarrer vLLM avec un modèle pour le codage
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

# Attendre le chargement du modèle (~2-5 min)
docker logs -f vllm | grep "Application startup"

# 2. Démarrer OpenHands avec le backend vLLM
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
```

> Voir le [guide vLLM](/guides/guides_v2-fr/modeles-de-langage/vllm.md) pour la configuration complète, les options de quantification et les configurations multi-GPU.

### Modèles locaux recommandés pour le codage

| Modèle                  | Taille | VRAM min | Qualité |
| ----------------------- | ------ | -------- | ------- |
| `qwen2.5-coder:7b`      | 7B     | 8 Go     | ★★★☆☆   |
| `deepseek-coder-v2:16b` | 16B    | 12 Go    | ★★★★☆   |
| `qwen2.5-coder:32b`     | 32B    | 24 Go    | ★★★★☆   |
| `llama3.1:70b`          | 70B    | 48 Go    | ★★★★★   |

***

## Conseils et bonnes pratiques

### 1. Utilisez judicieusement les montages de workspace

Montez votre répertoire de projet réel comme workspace afin qu'OpenHands puisse modifier directement vos fichiers :

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

### 2. Rédaction de tâches pour de meilleurs résultats

OpenHands fonctionne mieux avec des invites spécifiques et exploitables :

```
✅ Bien : "Corrigez le bug d'authentification dans src/auth/login.py où les tokens JWT 
         expirent immédiatement. Le problème se situe dans le calcul de l'expiration du token."

❌ Mal : "Corrigez le bug"
```

### 3. Surveillez l'utilisation des ressources

```bash
# Surveillez l'utilisation GPU et mémoire
watch -n 2 'nvidia-smi && docker stats --no-stream'
```

### 4. Définir des limites d'itération

Empêchez les agents hors de contrôle de consommer trop de tokens d'API :

```bash
-e MAX_ITERATIONS=50  # Limiter à 50 étapes par tâche
```

### 5. Intégration GitHub

OpenHands peut résoudre des issues GitHub directement. Configurez dans l'UI :

* Token GitHub : votre token d'accès personnel avec `repo` portée
* OpenHands clonera le repo, corrigera le problème et créera une PR

### 6. Estimation des coûts

Pour les LLM basés sur API, estimez le coût par tâche :

* Correction de bug simple : \~0,05–0,15 $ (Claude Haiku/GPT-4o-mini)
* Fonctionnalité complexe : \~0,50–2,00 $ (Claude Sonnet/GPT-4o)
* Pour 100+ tâches/jour, un LLM local sur Clore.ai s'amortit

***

## Dépannage

### Permission du socket Docker refusée

```bash
# Erreur : permission refusée lors de la tentative de connexion au daemon Docker
# Correction : assurez-vous que le socket est accessible
ls -la /var/run/docker.sock
# Devrait afficher : srw-rw---- 1 root docker ...

# Ajoutez votre utilisateur au groupe docker si nécessaire
usermod -aG docker $USER
# Puis redémarrez le shell ou utilisez : newgrp docker
```

### Le conteneur sandbox ne démarre pas

```bash
# Vérifiez si l'image runtime est accessible
docker pull ghcr.io/all-hands-ai/runtime:0.38-nikolaik

# Vérifiez les limites de taux GHCR (peut nécessiter une authentification)
docker login ghcr.io
```

### Le port 3000 n'est pas accessible

```bash
# Vérifiez que le conteneur tourne et que le port est lié
docker ps | grep openhands
docker port openhands

# Vérifiez le pare-feu Clore.ai — assurez-vous que le port 3000 figure dans votre mappage de ports
# Dans le tableau de bord Clore.ai : Serveur → Ports → Ajouter 3000:3000
```

### Erreurs de connexion LLM avec Ollama

```bash
# Testez qu'Ollama est atteignable depuis le conteneur OpenHands
docker exec openhands curl http://host.docker.internal:11434/api/tags

# Si cela échoue, vérifiez que le flag --add-host a été inclus dans le docker run
# Vérifiez aussi que le conteneur Ollama est en cours d'exécution :
docker ps | grep ollama
docker logs ollama | tail -20
```

### Les boucles d'agent tournent indéfiniment

```bash
# Réduire le nombre maximal d'itérations
docker stop openhands
docker run ... -e MAX_ITERATIONS=30 ...

# Ou définir un timeout
-e SANDBOX_TIMEOUT=60
```

### Plus de mémoire (OOM)

```bash
# Vérifier l'utilisation de la mémoire
free -h
docker stats

# Si vous exécutez un LLM local, essayez un modèle plus petit
docker exec ollama ollama pull qwen2.5-coder:3b

# Ou utilisez une version quantifiée (moins de VRAM)
docker exec ollama ollama pull llama3.1:8b-instruct-q4_K_M
```

***

## Lectures complémentaires

* [Dépôt GitHub d'OpenHands](https://github.com/All-Hands-AI/OpenHands) — Code source, issues et releases
* [Documentation OpenHands](https://docs.all-hands.dev) — Docs officiels incluant la configuration des LLM
* [Ollama sur Clore.ai](/guides/guides_v2-fr/modeles-de-langage/ollama.md) — Exécuter des LLM locaux pour l'inférence d'agents gratuite
* [vLLM sur Clore.ai](/guides/guides_v2-fr/modeles-de-langage/vllm.md) — Service de LLM locaux haute performance
* [Guide de comparaison GPU](/guides/guides_v2-fr/prise-en-main/gpu-comparison.md) — Choisir le bon GPU pour votre charge de travail
* [Discord OpenHands](https://discord.gg/ESHStjSjD4) — Support communautaire et recommandations de modèles
* [Leaderboard SWE-bench](https://www.swebench.com) — Comparer la performance des agents sur de vraies issues GitHub


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-fr/plateformes-et-agents-ia/openhands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.