> 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-ia-et-agents/openhands.md).

# Développeur IA OpenHands

Déployez OpenHands (anciennement OpenDevin) sur Clore.ai — exécutez un ingénieur logiciel IA entièrement autonome sur des serveurs cloud GPU abordables pour le codage, le débogage et la résolution d'incidents GitHub.

## Aperçu

[OpenHands](https://github.com/All-Hands-AI/OpenHands) (anciennement OpenDevin) est une plateforme open source d'agents logiciels IA autonomes. Avec plus de 65 000 étoiles 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 bogues, résoudre des problèmes GitHub, exécuter des commandes shell, naviguer sur le Web et interagir de bout en bout avec votre base de code.

Contrairement aux outils de complétion de code classiques, 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, le coupler avec un **LLM local** (Ollama, vLLM) sur le même serveur élimine les coûts d'API et la latence
* Les serveurs GPU abordables de Clore.ai vous permettent d'exécuter à la fois OpenHands et un modèle local pour seulement **$0.20–$0.35/h**
* Vous bénéficiez d'un stockage persistant de l'espace de travail, de la prise en charge de Docker-in-Docker et d'un accès root complet
* Idéal pour les tâches autonomes de longue durée qui seraient coûteuses via des API LLM cloud

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

* Génération autonome de code à partir d'un cahier des charges ou d'une description de problème
* 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 en interne un conteneur d'exécution isolé. 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,07–0,21 $/h                             |
| **+ Ollama (Qwen2.5 32B)**            | RTX 4090                          | 24 Go | 32 Go | 60 Go    | 0,14–0,42 $/h                             |
| **+ vLLM (Llama 3.1 70B)**            | A100 80 Go                        | 80 Go | 64 Go | 100 Go   | [bare metal](https://clore.ai/bare-metal) |
| **+ vLLM (Llama 3.3 70B INT4)**       | RTX 4090                          | 24 Go | 32 Go | 80 Go    | 0,14–0,42 $/h                             |

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

**Configuration logicielle requise 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 les images GHCR

***

## Démarrage rapide

### Étape 1 : Sélectionner et se connecter à un serveur Clore.ai

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

* RAM ≥ 16 Go (pour la combinaison avec un LLM local)
* Docker : ✓ activé
* Choisissez le GPU de votre choix 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érifier que Docker fonctionne

```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 autre image.

### Étape 3 : Télécharger et exécuter OpenHands

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

# Exécuter OpenHands (télécharge l'image 0.38 la plus récente 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 modèles restreignent les ports externes — vérifiez la section "Ports" dans les détails de votre serveur.

Au premier lancement, OpenHands vous invitera à configurer un fournisseur LLM.

### Étape 5 : Configurer 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 configuré entièrement 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 (par ex. `gpt-4o`, `claude-3-5-sonnet-20241022`) | Défini dans l'interface          |
| `LLM_API_KEY`     | Clé API du fournisseur LLM                                             | Défini dans l'interface          |
| `LLM_BASE_URL`    | URL de base personnalisée (pour Ollama, vLLM, LiteLLM)                 | Valeur par défaut du fournisseur |
| `SANDBOX_TIMEOUT` | Délai d'expiration du bac à sable 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 sous lequel exécuter le bac à sable (utiliser `$(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 les 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

# Afficher les journaux
docker logs -f openhands
```

***

## Accélération GPU (intégration d'un LLM local)

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

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

Lancez d'abord Ollama, puis pointez OpenHands vers lui :

```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. Télécharger 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 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 des modèles, l'optimisation des performances et la configuration GPU.

### Option B : OpenHands + vLLM (hautes performances)

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

```bash
# 1. Démarrer vLLM avec un modèle de 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 minimale | 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 l'espace de travail

Montez votre véritable répertoire de projet comme espace de travail 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. Formulation de la tâche pour de meilleurs résultats

OpenHands fonctionne mieux avec des prompts précis et exploitables :

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

❌ Mauvais : "Corrige le bug"
```

### 3. Surveillez l'utilisation des ressources

```bash
# Surveiller l'utilisation du GPU et de la 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 jetons API :

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

### 5. Intégration GitHub

OpenHands peut résoudre directement les problèmes GitHub. Configurez-le dans l'interface :

* Jeton GitHub : Votre jeton d'accès personnel avec `repo` portée
* OpenHands clonera le dépôt, 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 simple de bogue : \~0,05–0,15 $ (Claude Haiku/GPT-4o-mini)
* Fonctionnalité complexe : \~0,50–2,00 $ (Claude Sonnet/GPT-4o)
* Pour plus de 100 tâches/jour, un LLM local sur Clore.ai est rentabilisé

***

## Dépannage

### Refus d'autorisation du socket Docker

```bash
# Erreur : autorisation refusée lors de la tentative de connexion au démon 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
```

### Échec du démarrage du conteneur sandbox

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

# Vérifiez les limites de débit GHCR (une authentification peut être nécessaire)
docker login ghcr.io
```

### Le port 3000 n'est pas accessible

```bash
# Vérifiez que le conteneur est en cours d'exécution 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 au LLM avec Ollama

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

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

### La boucle de l'agent se répète indéfiniment

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

# Ou définissez un délai d'expiration
-e SANDBOX_TIMEOUT=60
```

### Mémoire insuffisante (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
```

***

## Pour aller plus loin

* [Dépôt GitHub d'OpenHands](https://github.com/All-Hands-AI/OpenHands) — Code source, problèmes et versions
* [Documentation OpenHands](https://docs.all-hands.dev) — Documentation officielle, y compris la configuration du LLM
* [Ollama sur Clore.ai](/guides/guides_v2-fr/modeles-de-langage/ollama.md) — Exécutez des LLM locaux pour une inférence d'agent gratuite
* [vLLM sur Clore.ai](/guides/guides_v2-fr/modeles-de-langage/vllm.md) — Service de LLM local haute performance
* [Guide de comparaison des GPU](/guides/guides_v2-fr/premiers-pas/gpu-comparison.md) — Choisissez le bon GPU pour votre charge de travail
* [Discord OpenHands](https://discord.gg/ESHStjSjD4) — Support communautaire et recommandations de modèles
* [Classement SWE-bench](https://www.swebench.com) — Comparez les performances des agents sur de vrais problèmes 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.