Démarrage rapide de l’interface en ligne de commande OpenHands : installation, options et mode sans interface

OpenHands est un agent de codage open source qui modifie des fichiers et exécute des commandes dans un bac à sable. Cette introduction rapide CLI a été vérifiée le 26/10/2026 par rapport au package 1.16.0.

Le package sur PyPI est openhands 1.16.0, téléversé le 8 mai 2026, verrouillé sur openhands-sdk==1.21.0. Le README de sa balise exige Python 3.12 et uv 0.11.6 ou plus récent. Le README de la branche par défaut d’OpenHands-CLI indique que ce dépôt n’est plus activement maintenu et oriente les nouvelles installations vers Agent Canvas. Le mode sans interface graphique et openhands acp font toujours partie du jeu de commandes de la 1.16.0.

Le guide des outils de développement IA suit les autres agents de terminal sur ce site. Cette page reste sur le CLI OpenHands : installation, fichiers de configuration, URL de modèles locaux et les drapeaux qu’un script transmet réellement.

De quoi le CLI est-il

Un assistant de codage IA génère généralement ou modifie du code à partir d’un prompt. OpenHands étend cela en une boucle agentique : planifier, effectuer une action telle que l’écriture d’un fichier ou l’exécution d’un test, observer le résultat, et continuer. Le projet s’appelait auparavant OpenDevin. Le papier OpenHands décrit un runtime bac à sable Docker avec un shell et une navigation web, qui est le modèle d’exécution que le CLI enveloppe encore.

La publication 1.16.0 documente cinq façons d’exécuter cette boucle.

Agent Canvas, l’installation que le projet documente désormais

Le 3 juin 2026, la FAQ d’OpenHands a placé l’interface utilisateur de terminal en maintenance jusqu’au 1er octobre 2026, et a déclaré que le mode sans interface graphique et l’ACP resteraient entièrement pris en charge. La GUI locale (openhands serve) était censée rester en maintenance jusqu’à ce qu’Agent Canvas puisse exécuter des bac à sable isolés et éphémères. Cette FAQ définit la maintenance comme des mises à jour de dépendances, des correctifs de bugs critiques et de nouveaux LLM. Le dépôt principal d’OpenHands a livré Agent Canvas 1.33.0 le 23 octobre 2026.

agent-canvas démarre l’interface utilisateur actuelle et son backend. openhands serve démarre la GUI héritée et ne démarre pas Agent Canvas.

Agent Canvas a besoin de Node.js 24 ou plus récent et de uv. Une première exécution sans installation globale :

npx @openhands/agent-canvas

Le processus écoute sur http://localhost:8000. Fermer ce terminal arrête le backend local. Une installation globale est npm install -g @openhands/agent-canvas, puis agent-canvas. Le chemin npm exécute le serveur agent en tant qu’utilisateur, de sorte que l’agent peut agir sur les fichiers locaux avec les autorisations de votre compte.

Le chemin Docker publie le port uniquement sur localhost et monte un répertoire de projets :

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

Le conteneur sert l’interface utilisateur sur http://localhost:8000/canvas. Le volume nommé openhands-data conserve les configurations après --rm. Sur Linux, la liaison par montage de ~/.openhands dans cette image échoue avec unable to open database file : l’utilisateur du conteneur a pour UID 10001, et un répertoire hôte est généralement propriétaire de votre propre UID. La page d’installation utilise le volume nommé pour cette raison. Les configurations déjà présentes dans ~/.openhands ne sont pas copiées dans un nouveau volume.

Installer le CLI OpenHands

Utilisez le CLI lorsque vous souhaitez toujours utiliser openhands --headless ou openhands acp. La roue publiée s’installe uniquement sur Python 3.12 (==3.12.* sur PyPI). uv doit être 0.11.6 ou plus récent. Sur Windows, la page d’installation indique d’exécuter les commandes dans WSL (Ubuntu).

Installer avec uv

uv tool install openhands --python 3.12
openhands

Mettre à niveau avec le même verrouillage d’interpréteur :

uv tool upgrade openhands --python 3.12

La page de configuration locale indique qu’uv est ce qui isole le CLI de l’environnement virtuel du projet, et que les serveurs MCP par défaut l’exigent.

Installer le binaire autonome

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

Sur macOS, une boîte de dialogue Gatekeeper peut bloquer le binaire (“openhands ne peut pas être ouvert car Apple ne peut pas vérifier s’il contient un logiciel malveillant”). Le chemin de la page d’installation est Paramètres Système, Confidentialité et sécurité, puis Autoriser quand même sous Sécurité, puis exécuter openhands à nouveau.

Exécuter le CLI via Docker

Le conteneur de la page d’installation définit AGENT_SERVER_IMAGE_TAG sur l’image agent-server. Le uv tool install openhands dans le conteneur est le CLI de PyPI. La balise dans cet exemple, vérifiée pour cette page, est 1.26.0-python. Les anciennes copies de cette commande utilisaient 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) fait correspondre l’utilisateur du bac à sable à l’utilisateur hôte, de sorte que l’agent ne laisse pas de fichiers possédés par root dans l’espace de travail monté. SANDBOX_VOLUMES est le répertoire auquel l’agent peut accéder.

OPENHANDS_VERSION sélectionne la version de l’image Docker pour openhands serve. Cela ne change pas la version du CLI de PyPI.

Fichiers de configuration

Au premier lancement, le CLI demande les paramètres du modèle et les écrit sous ~/.openhands/. Le README de la 1.16.0 et la référence des commandes nomment ces fichiers :

La page d’installation indique encore aux utilisateurs Docker de préparer ~/.openhands/settings.json. Le README du CLI et AgentStore dans l’arborescence 1.16.0 persistent la spécification agent dans agent_settings.json. Une installation CLI qui a ignoré le nom de fichier de la page d’installation et a écrit agent_settings.json correspond à cette source.

create_and_save_from_settings construit deux objets LLM à partir du même modèle, clé API et URL de base : l’un pour l’agent et l’autre pour le condenseur de résumé. C’est pourquoi un fichier enregistré répète les champs llm. Modifier le fichier agent avec n’importe quel éditeur :

nano ~/.openhands/agent_settings.json

LLM_API_KEY, LLM_MODEL et LLM_BASE_URL sont ignorés sauf si vous optez pour l’utilisation de variables d’environnement. La surcharge n’est pas enregistrée :

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="votre-cle-api"
openhands --override-with-envs

OPENHANDS_CLOUD_URL définit le serveur cloud par défaut. Les commandes cloud et login par défaut sur https://app.all-hands.dev lorsque cette variable n’est pas définie.

Les mises à niveau depuis un CLI antérieur à la 1.0.0 nécessitent la saisie à nouveau des configurations. La page d’installation indique que le format de configuration a changé à la version 1.0.0.

Modèles locaux

Le guide des LLM locaux daté du 21 mai 2026 recommande Qwen3.6-35B-A3B comme premier modèle local à essayer. Il demande un GPU avec au moins 24 Go de mémoire VRAM pour un build quantifié, ou un Mac Apple Silicon avec au moins 64 Go de mémoire unifiée. La même page indique de définir la longueur de contexte à au moins 22 000 jetons, et que la valeur par défaut d’Ollama de 4096 est trop petite pour le prompt système.

Lorsque l’agent n’appelle jamais d’outils, le guide considère cela comme une limite du modèle et cite des rapports de la communauté pour qwen2.5-coder-14b-instruct et qwopus3.5-27b-v3. La comparaison d’hébergement local est le tableau serveur par serveur lorsque Ollama, vLLM, LM Studio ou LocalAI est toujours un choix ouvert.

Ollama

Le lancement Ollama du guide définit la longueur de contexte avant ollama serve. L’aide-mémoire CLI Ollama couvre serve, run et ps à côté de cette variable.

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

Pour OpenHands exécuté dans Docker, les configurations du guide sont le modèle personnalisé openai/qwen3.6:35b-a3b, l’URL de base http://host.docker.internal:11434/v1, et n’importe quelle clé API de remplacement. Un CLI exécuté sur le même hôte que Ollama utilise http://127.0.0.1:11434/v1 au lieu de host.docker.internal. Les serveurs en boucle locale uniquement comme LM Studio sur Linux et autres sont inaccessibles depuis un conteneur à 127.0.0.1 ; la vérification du guide est d’activer le service sur le réseau local et de faire un curl de host.docker.internal depuis l’intérieur du conteneur.

La page du terminal ouvre cet écran avec Ctrl+P, puis Paramètres. Un profil CLI enregistré utilisait un identifiant de modèle ollama/ et une URL de base sans /v1 :

• Modèle personnalisé : ollama/devstral-small-2:24b
• URL de base : http://localhost:11434

Cette session Devstral-Small-2 est celle qui s’arrêtait constamment. Les champs écrits pour elle, dans les deux objets LLM, agent et condenseur, étaient :

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

llama.cpp et vLLM

llama.cpp utilisait le préfixe compatible OpenAI et une URL de base /v1, encore une fois dans les deux objets LLM :

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

La commande du serveur, avec les drapeaux couverts dans l’introduction rapide llama.cpp, était :

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

Face à ce serveur, le CLI a terminé un client Go IndexNow : source, un exécutable et un README. Le texte de la tâche était 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.

L’exemple vLLM du guide des LLM locaux pour le modèle Qwen3.6 plus récent est un service sur deux GPU. L’introduction rapide vLLM passe en revue les drapeaux vllm serve et les vérifications de mémoire insuffisante. La chaîne de modèle OpenHands correspondante du guide est openai/Qwen3.6-35B-A3B, avec l’URL de base http://host.docker.internal:8000/v1 et le même --api-key avec lequel le serveur a été démarré (mykey dans leur exemple).

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

Commandes interactives

openhands sans sous-commande ouvre l’interface utilisateur de terminal. La page du terminal liste ces commandes :

Commandes en barre oblique de la référence des commandes : /help, /new, /history, /confirm, /condense, /skills, /feedback, /exit. Les changements de modèle depuis l’entrée Paramètres de la palette s’appliquent sans redémarrage. --exit-without-confirmation saute la boîte de dialogue de sortie. --exp sélectionne l’interface utilisateur textuelle et est documenté comme un drapeau de compatibilité car cette interface est déjà le défaut.

Drapeaux et sous-commandes

openhands [OPTIONS] [COMMAND]

Options globales de la référence des commandes, vérifiées contre argparsers/util.py sur la balise 1.16.0 pour les drapeaux d’approbation et d’environnement :

--always-approve et --llm-approve ne peuvent pas être combinés. Le mode interactif par défaut demande avant les actions.

Sous-commandes qui apparaissent une fois que l’interface utilisateur de terminal ne suffit plus :

• openhands serve démarre la GUI héritée dans Docker. --mount-cwd monte le répertoire actuel à /workspace. --gpu active nvidia-docker.
• openhands web sert le CLI dans un navigateur. --host par défaut sur 0.0.0.0, --port sur 12000, --debug est désactivé.
• openhands acp parle le protocole Agent Client Protocol sur stdio. Drapeaux : --resume, --last, --always-approve, --llm-approve, --streaming.
• openhands cloud -t "tâche" ouvre une conversation cloud. --server-url surcharge https://app.all-hands.dev.
• openhands login et openhands logout gèrent ce compte cloud. logout sans --server-url se déconnecte de tous les serveurs enregistrés.
• openhands mcp gère les serveurs : add, list, get, remove, enable, disable. add exige un --transport de type http, sse ou stdio.

Un serveur MCP du README de la 1.16.0 :

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

Exemples

Tâche interactive

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

Fichier de tâche

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

openhands -f task.txt

Sans interface graphique, incluant JSONL

Le mode sans interface graphique exige --task ou --file. Il s’exécute toujours en mode approbation totale, et --llm-approve est rejeté là-bas. Considérer le répertoire de travail comme un lieu que l’agent peut modifier librement.

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

La page sans interface graphique décrit --json comme un objet JSON par événement, diffusé en JSONL.

Reprendre

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

TUI navigateur lié à localhost

openhands web par défaut sur 0.0.0.0:12000, ce qui est accessible depuis le réseau. La documentation du CLI indique que cette interface a toute la capacité du CLI, donc une liaison locale uniquement est le défaut plus sûr :

openhands web --host 127.0.0.1 --port 12000

ACP pour un éditeur

Les clients ACP de la page IDE sont Zed et JetBrains (natif), Toad (natif), et VS Code (extension communautaire). L’éditeur démarre openhands acp et parle JSON-RPC 2.0 sur stdio, en utilisant les configurations LLM enregistrées du CLI.

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

Approbation, codes de sortie et résultats des modèles locaux

Les sessions interactives demandent avant les actions. /confirm change cette politique dans la session. --always-approve (alias --yolo) approuve tout. --llm-approve demande uniquement pour les actions que l’analyseur de sécurité note à haut risque. Le mode sans interface graphique est en approbation totale pour toute l’exécution.

openhands serve --mount-cwd monte le répertoire actuel à /workspace dans le conteneur GUI hérité. Le flux CLI Docker utilise SANDBOX_VOLUMES pour la même frontière.

Codes de sortie dans la référence des commandes :

Devstral-Small-2 24B sur Ollama s’est arrêté à plusieurs reprises dans ce CLI.

La session llama.cpp ci-dessus, Qwen3.5-35B-A3B dans un contexte de 70 000 jetons, a terminé la tâche IndexNow. Pour un agent de terminal qui a continué à travailler sur la même machine, l’introduction rapide OpenCode est l’installation et la configuration du fournisseur.