Début rapide de l'assistant de codage OpenHands : installation, options de ligne de commande et exemples

Démarrage rapide d'OpenHands CLI en quelques minutes

Sommaire

OpenHands est une plateforme open-source et agnostique des modèles pour les agents de développement logiciel pilotés par l’IA. Il permet à un agent de se comporter davantage comme un partenaire de codage que comme un simple outil de complétion automatique.

Il peut travailler avec des fichiers, exécuter des commandes dans un environnement sandboxé et utiliser la navigation web lorsque nécessaire.

Ce guide de démarrage rapide se concentre sur le CLI OpenHands, car c’est le moyen le plus rapide d’être productif depuis votre terminal, et il correspond parfaitement aux modèles d’automatisation comme les scripts et les exécutions CI. Pour une vue d’ensemble plus large du domaine, consultez Outils pour développeurs IA : Le guide complet du développement assisté par IA.

interface textuelle openhands

Qu’est-ce qu’OpenHands et en quoi il est différent

Un assistant de codage IA vous aide généralement à générer ou modifier du code en utilisant un modèle de langue. OpenHands étend cette idée vers un flux de travail « agencé » : le système peut planifier de manière itérative, prendre des actions (comme écrire des fichiers ou exécuter des tests), observer les résultats et continuer jusqu’à ce que la tâche soit terminée.

OpenHands est également largement connu sous le nom de projet anciennement appelé OpenDevin, et il s’est développé en une plateforme communautaire avec plusieurs façons de l’utiliser : un CLI, une interface graphique web locale, une interface hébergée dans le cloud et un SDK.

D’un point de vue ingénierie, la différenciation clé est qu’OpenHands est construit autour d’un environnement d’exécution (un sandbox) permettant à un agent d’exécuter en toute sécurité des commandes et des outils, plutôt que de produire uniquement du texte. L’article OpenHands décrit un environnement d’exécution sandboxé Docker avec un shell et des capacités de navigation, spécifiquement pour supporter des modèles d’interaction réalistes similaires à ceux des développeurs.

Installer le CLI OpenHands

OpenHands prend en charge plusieurs méthodes d’installation. Pour la plupart des développeurs, il est préférable de commencer par une installation locale du CLI (itération rapide) et d’ajouter optionnellement des flux de travail basés sur Docker plus tard lorsque vous souhaitez une isolation stricte autour de l’exécution.

Installer avec uv

La documentation actuelle du CLI OpenHands recommande l’installation via uv et nécessite Python 3.12+.

uv tool install openhands --python 3.12
openhands

La mise à niveau est tout aussi simple.

uv tool upgrade openhands --python 3.12

Pourquoi uv est important en pratique : uv offre une meilleure isolation de votre environnement de projet actuel et est requis pour les serveurs MCP par défaut.

Installer le binaire CLI autonome

Si vous souhaitez un flux d’installation en « une seule commande », OpenHands fournit un script d’installation.

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

Sur macOS, vous devrez peut-être autoriser explicitement le binaire dans Confidentialité & Sécurité avant qu’il ne s’exécute.

Exécuter via Docker pour l’isolation

Si vous préférez garder l’installation contenue, la documentation du CLI montre également un flux basé sur Docker. Cette approche repose sur le montage d’un répertoire que vous souhaitez que OpenHands accède et le passage de votre ID utilisateur pour éviter de créer des fichiers appartenant à root dans l’espace de travail monté.

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"

Configuration du premier exécution et localisation des paramètres

Lors de la première exécution, le CLI vous guide à travers la configuration des paramètres LLM requis et les stocke pour les sessions futures. La documentation du CLI indique que les paramètres sont sauvegardés sous ~/.openhands/settings.json et l’historique des conversations est stocké dans ~/.openhands/conversations, mais lorsque j’ai installé OpenHands récemment, il a stocké la configuration dans ~/.openhands/agent_settings.json, donc la documentation n’est peut-être pas tout à fait exacte.

Pour une configuration plus approfondie et une intégration d’outils, OpenHands documente également des fichiers de configuration supplémentaires tels que ~/.openhands/agent_settings.json (paramètres de l’agent et du LLM), ~/.openhands/cli_config.json (préférences du CLI) et ~/.openhands/mcp.json (serveurs MCP).

Configurer OpenHands avec Ollama local et llama.cpp

OpenHands fonctionne avec n’importe quel backend local compatible avec OpenAI — Ollama, LocalAI, llama.cpp et autres. Si vous n’êtes pas sûr de celui à utiliser, consultez Ollama vs vLLM vs LM Studio : La meilleure façon d’exécuter des LLM localement pour une comparaison.

Lorsque vous démarrez OpenHands pour la première fois, il vous affiche la page de paramètres. Une fois cette étape de premier passage franchie, vous pouvez rouvrir cette page en tapant /settings puis ctrl+j. Maintenant tapez :

  • dans le champ Custom Model : ollama/devstral-small-2:24b, ou votre modèle local préféré,
  • et dans le champ Base Url : http://localhost:11434

paramètres openhands ollama mistral

Pour une référence rapide sur les commandes Ollama, consultez la Fiche de triche du CLI Ollama : serve, run, ps et gestion des modèles.

Pour éditer manuellement le fichier de configuration OpenHands, par exemple si vous n’aimez pas l’apparence de la page de paramètres, exécutez :

nano ~/.openhands/agent_settings.json

ou si vous préférez un éditeur avec plus d’interface graphique :

gedit GUI ~/.openhands/agent_settings.json

Il y a une propriété llm en deux endroits, je les ai configurées pour avoir ces sous-propriétés entre autres pour pointer vers Ollama :

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

Pour pointer OpenHands vers une instance locale de llama.cpp - c’est la même chose, en deux endroits :

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

Pour me connecter à llama.cpp, j’ai configuré :

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

et j’ai démarré llama.cpp avec la commande (voir Démarrage rapide de llama.cpp avec CLI et Serveur pour les détails des drapeaux) :

./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 a pu se connecter et a complété ma demande de test crée-moi un outil CLI en Go qui appellerait les endpoints indexnow de Bing et d'autres moteurs de recherche pour notifier des changements sur mon site avec succès - avec le code source, un exécutable et un README.md.

Comment le CLI OpenHands fonctionne en pratique

La commande openhands par défaut lance une expérience terminal interactive. OpenHands fournit une palette de commandes et des commandes en session pour que vous puissiez orienter rapidement l’agent pendant qu’il travaille.

Les contrôles interactifs utiles à connaître tôt incluent l’ouverture de la palette de commandes, la pause de l’agent et la sortie de l’application.

  • Ctrl+P ouvre la palette de commandes.
  • Esc met l’agent en cours d’exécution en pause.
  • Ctrl+Q ou /exit quitte le CLI.

À l’intérieur du CLI, OpenHands prend également en charge des commandes avec préfixe barre oblique comme /help, /new et /condense, ce qui est précieux si vous voulez gérer de longues conversations sans redémarrer.

OpenHands ne s’arrête pas à une interface terminal. Le CLI inclut plusieurs interfaces qui correspondent bien à différents flux de travail de développeurs :

  • Mode sans tête (Headless) pour l’automatisation et la CI.
  • Interface web pour exécuter l’expérience du CLI dans un navigateur.
  • Serveur GUI pour l’application web locale complète, lancée via Docker.
  • Intégration IDE via ACP pour les flux de travail basés sur l’éditeur.

Principaux paramètres de ligne de commande que vous utiliserez réellement

De manière générale, le CLI OpenHands suit cette structure :

openhands [OPTIONS] [COMMAND]

Cela inclut les options globales (comme les tâches, la reprise, le mode sans tête), plus les sous-commandes (serve, web, cloud, acp, mcp, login, logout).

Options principales pour le travail quotidien

Les options globales les plus couramment utilisées sont :

  • -t, --task pour amorcer la conversation avec une tâche initiale.
  • -f, --file pour amorce depuis un fichier, ce qui est pratique lorsque vous voulez des tâches soumises au contrôle de version.
  • --resume [ID] et --last pour reprendre des exécutions précédentes.
  • --headless pour une exécution non interactive, typiquement en automatisation.
  • --json pour diffuser une sortie JSONL en mode sans tête pour le parsing machine.

La sécurité et les approbations sont également de première classe :

  • --always-approve approuve automatiquement les actions sans demande de confirmation.
  • --llm-approve utilise un analyseur de sécurité basé sur un LLM pour l’approbation des actions.

Configuration du modèle et du fournisseur via variables d’environnement

OpenHands prend en charge les variables d’environnement pour la configuration du modèle :

  • LLM_API_KEY définit votre clé d’API fournisseur.
  • LLM_MODEL et LLM_BASE_URL peuvent être appliqués comme remplacements lorsque vous exécutez openhands --override-with-envs.

Exemple de flux de remplacement :

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

OpenHands note explicitement que les remplacements appliqués avec --override-with-envs ne sont pas persistés.

Sous-commandes à connaître

Vous n’avez pas besoin de chaque sous-commande dès le premier jour, mais ce sont celles qui apparaissent rapidement :

  • openhands serve lance le serveur GUI complet utilisant Docker, généralement accessible sur http://localhost:3000, avec des options comme --mount-cwd et --gpu.
  • openhands web lance le CLI comme une application web accessible par navigateur, par défaut sur le port 12000.
  • openhands login authentifie avec OpenHands Cloud et récupère vos paramètres.
  • openhands cloud crée une nouvelle conversation dans OpenHands Cloud depuis le CLI.

Exemples à copier et coller que vous pouvez utiliser immédiatement

Le moyen le plus rapide de tirer valeur de OpenHands est de le traiter comme un agent de codage piloté par des tâches. Gardez les tâches concises, incluez des noms de fichiers et demandez des tests ou une vérification lorsque c’est approprié.

Démarrer une session de codage interactive avec une tâche initiale

C’est l’« expérience développeur par défaut » et l’un des modèles les plus courants.

openhands -t "Corriger le bug dans auth.py et ajouter un test de régression"

La documentation du CLI OpenHands montre exactement cette idée pour amorcer une session avec -t.

Amorcer une tâche depuis un fichier

Utiliser un fichier est utile lorsque vous voulez la répétabilité, une revue d’équipe ou une réutilisation CI.

cat > task.txt << 'EOF'
Refactorer le module de connexion à la base de données.
Ajouter des tests unitaires et s'assurer que la suite de tests passe.
EOF

openhands -f task.txt

Le Guide de Démarrage Rapide du CLI prend explicitement en charge le démarrage depuis un fichier de tâche avec -f.

Exécuter en mode sans tête pour la CI ou l’automatisation

Le mode sans tête s’exécute sans l’interface interactive et est conçu pour les pipelines CI et le script automatisé.

openhands --headless -t "Ajouter des tests unitaires pour auth.py et les exécuter"

Deux réalités d’ingénierie importantes ici :

  • Le mode sans tête nécessite --task ou --file.
  • Le mode sans tête s’exécute toujours en mode toujours-approuvé et ne peut pas être modifié, et --llm-approve n’est pas disponible en mode sans tête. Traitez-le comme une automatisation puissante et exécutez-le dans un environnement contrôlé.

Pour intégrer avec l’analyse de logs ou d’autres outils, activez la sortie JSONL :

openhands --headless --json -t "Créer une application Flask simple avec un endpoint de santé" > openhands-output.jsonl

OpenHands documente --json comme un streaming d’événements JSONL en mode sans tête et montre la redirection de la sortie vers un fichier.

Reprendre le travail sans perdre le contexte

La reprise est critique une fois que vous commencez à utiliser OpenHands pour des changements non triviaux.

Lister les conversations récentes :

openhands --resume

Reprendre la plus récente :

openhands --resume --last

Ou reprendre un ID de conversation spécifique :

openhands --resume abc123def456

Ces flux sont documentés dans la référence de commande CLI et le guide « Reprise des conversations ».

Exécuter le CLI dans un navigateur lorsque vous en avez besoin

openhands web démarre un CLI accessible par le web (port par défaut 12000).

openhands web

Si vous exécutez localement, se lier uniquement à localhost est une valeur par défaut sensée :

openhands web --host 127.0.0.1 --port 12000

OpenHands avertit que l’exposition de l’interface web au réseau nécessite des mesures de sécurité appropriées, car elle fournit un accès complet aux capacités d’OpenHands.

Sécurité, dépannage et points sensibles

Le levier de sécurité le plus important dans le CLI OpenHands est les approbations :

  • Le CLI interactif peut demander une confirmation avant des actions sensibles, et vous pouvez configurer les paramètres de confirmation en session.
  • --always-approve supprime les frictions mais aussi les garde-fous.
  • --llm-approve ajoute un analyseur basé sur un LLM pour les approbations.
  • Le mode sans tête approuve toujours, donc réservez-le pour l’automatisation dans des environnements contrôlés.

Lors du travail avec du code local, privilégiez des modèles d’accès explicites et de privilèges minimaux :

  • Pour le serveur GUI, openhands serve --mount-cwd monte votre répertoire actuel vers /workspace afin que l’agent puisse lire et modifier vos fichiers de projet.
  • Pour les exécutions CLI basées sur Docker, utilisez SANDBOX_VOLUMES pour définir exactement quels répertoires OpenHands peut accéder.

Si vous avez d’anciens répertoires d’état OpenHands, OpenHands note un chemin de migration de ~/.openhands-state vers ~/.openhands dans la documentation de configuration locale et les conseils de dépannage.

Enfin, si vous intégrez OpenHands dans des scripts, les codes de sortie sont documentés comme suit :

  • 0 succès
  • 1 erreur ou tâche échouée
  • 2 arguments invalides

Mon expérience avec OpenHands

Pour moi, OpenHands a bien fonctionné, mais pas toujours… J’ai essayé de le faire fonctionner avec Devstral-Small-2 hébergé sur Ollama, et il s’arrêtait constamment.

OpenHands avec Devstral-Small-2 hébergé sur Ollama.

Bien qu’OpenHands ait bien fonctionné avec Qwen 3.5 35b hébergé localement sur llama.cpp. Pour l’instant, pour moi, OpenCode est beaucoup plus fiable.