Comment utiliser AI OpenHands : Un guide pratique pour la configuration, les invites et les flux de travail réels
Si vous avez déjà souhaité qu'un développeur compétent puisse faire du pair programming avec vous 24 heures sur 24, 7 jours sur 7, AI OpenHands s'en approche étonnamment. C'est un "ingénieur IA" open-source qui peut lire votre dépôt, écrire du code, exécuter des terminaux, parcourir des documents et itérer, un peu comme un jeune développeur qui apprend vite et travaille sans relâche. Mais la puissance ne se révèle qu'une fois que vous l'avez correctement configuré et que vous avez appris à le diriger.
Ce guide vous explique étape par étape comment utiliser AI OpenHands, de l'installation aux flux de travail avancés, afin que vous puissiez livrer plus rapidement en toute confiance.
- Ce que nous allons aborder :
- Options d'installation et démarrage rapide
- Exécution d'OpenHands localement ou avec des modèles cloud
- Meilleures pratiques pour les invites, les dépôts et les tâches
- Flux de travail éprouvés pour le travail sur les fonctionnalités, le débogage, les tests et la documentation
- Garde-fous, confidentialité et collaboration
Important : OpenHands est activement développé par l'équipe All Hands et la communauté. La documentation officielle est votre étoile polaire pour les instructions et les conseils actuels. Vous pouvez également suivre les guides d'installation pratiques des praticiens qui ont documenté les configurations locales et de VM. Pour l'exécution avec des modèles locaux, la documentation comprend également des conseils spécifiques.
Qu'est-ce que AI OpenHands et pourquoi l'utiliser ?
Considérez AI OpenHands comme un coéquipier IA avec un clavier. Contrairement aux assistants qui ne font que chatter, OpenHands peut :
- Ouvrir et lire les fichiers du projet
- Utiliser un terminal pour exécuter des commandes, des tests et des linters
- Modifier le code dans les fichiers et les répertoires
- Naviguer sur le web (selon la configuration)
- Proposer et appliquer des plans étape par étape
Cela le rend idéal pour des tâches telles que l'implémentation de fonctionnalités, la correction de bugs, l'écriture de tests, la création de documents, le refactoring et la modernisation de bases de code. Au lieu de jongler avec les invites et le copier/coller, vous donnez un objectif à OpenHands et vous le laissez itérer, tout en supervisant ses mouvements.
Démarrage rapide : Le moyen le plus rapide d'utiliser OpenHands
Il existe plusieurs façons de démarrer. Votre choix dépend de si vous voulez utiliser un LLM cloud ou tout exécuter localement.
Option A : Utiliser un LLM Cloud (le plus facile)
- Suivez la documentation officielle "Start Building" et "Getting Started" pour installer et exécuter l'application. Généralement, vous devrez :
- Installer les prérequis (Docker, Node, Python, Git selon le chemin)
- Fournir une clé API pour un modèle cloud pris en charge (par exemple, OpenAI, Anthropic, ou d'autres que le projet prend en charge au moment donné)
- Lancer l'interface OpenHands et connecter votre référentiel
Cette voie vous permet d'être productif rapidement avec un minimum de surcharge de calcul.
Option B : Exécuter OpenHands avec un LLM local
- Si vous préférez garder le code et les invites hors du cloud ou si vous voulez éviter les coûts de l'API, utilisez le guide Local LLMs dans la documentation officielle.
- Configurer un modèle local compatible (via Ollama ou d'autres backends pris en charge au moment donné)
- Configurer les points de terminaison du modèle et les limites de contexte
- Vous assurer que votre machine dispose de suffisamment de VRAM/CPU et d'espace disque
Option C : Déployer sur une VM
- Si vous avez besoin d'un environnement dédié, des professionnels ont documenté comment lancer OpenHands sur une VM et construire une application en quelques minutes. Ceci est utile pour les équipes qui veulent une instance d'ingénieur IA stable et partagée.
Première exécution : Configuration du projet et cadrage de la tâche
OpenHands brille quand il peut voir votre code. Commencez par :
- Ouvrir le référentiel sur lequel vous voulez qu'il travaille.
- Exécuter ou indexer le projet afin qu'OpenHands puisse cartographier la structure.
- Lui donner un objectif clair avec des contraintes.
Bon exemple de cadrage de tâche :
- "Ajouter la réinitialisation du mot de passe utilisateur au service
auth en utilisant des liens email basés sur des jetons. Utiliser le module mailer existant. Ajouter des tests unitaires pour la génération et l'expiration des jetons. Ne pas modifier le schéma des données utilisateur."
Pourquoi ça marche :
- Il nomme le composant, la portée, les dépendances et les limites. Plus vous êtes clair, mieux OpenHands planifie et exécute.
Comment écrire des invites efficaces pour OpenHands
Considérez les invites comme des tickets concis. Les meilleures :
- Définissent le résultat : "Implémenter X avec des contraintes Y"
- Référencent les fichiers, les modules ou les tests : "Voir
auth/routes.py et tests/test_auth.py"
- Énoncent les contraintes : "Pas de modifications du schéma DB ; conserver les interfaces existantes"
- Incluent les critères d'acceptation : "Les tests doivent réussir :
pytest -k password_reset"
Modèle que vous pouvez réutiliser :
Objectif : <Ce que vous voulez construire ou corriger>
Contexte : <Fichiers pertinents, contraintes connues, services externes>
Acceptation : <À quoi ressemble le succès : tests, points de terminaison, métriques>
Limites : <Ce qu'il ne faut pas changer ou les approches à éviter>
Outils : <Commandes qu'il peut exécuter, scripts ou sources de données>
Flux de travail de base : Planifier → Exécuter → Vérifier → Affiner
OpenHands propose généralement un plan en plusieurs étapes. Voici comment le guider :
- Approuver ou ajuster son plan tôt. Poussez-le à exécuter les tests d'abord pour établir les échecs de base.
- Demandez-lui de créer ou de mettre à jour un test pour définir le succès, puis d'implémenter le code.
- Faites-lui exécuter la suite de tests et les linters fréquemment.
- S'il cale, ajoutez plus de contexte : noms de fichiers, traces de pile ou journaux.
Conseil de pro : Encouragez les petits changements de la taille d'une PR au lieu des modifications monolithiques. Cela aide à la révision et à la restauration.
Exemples de flux de travail que vous pouvez copier
1) Implémentation de fonctionnalité
- Invite : "Ajouter l'exportation CSV à la page
orders. Utiliser la pagination côté serveur, diffuser les résultats via text/csv. Ajouter le bouton Export dans OrdersTable.jsx et le point de terminaison dans routes/orders.ts. Inclure des tests pour la pagination et les en-têtes."
- Analyse le dépôt ; ébauche un plan
- Ajoute un point de terminaison et un bouton client
- Écrit des tests et les exécute
- Vous supervisez, approuvez les changements et fusionnez une fois que c'est bon.
2) Débogage d'une build en échec
- Invite : "CI échoue sur Node 20. Corriger les erreurs d'importation ESM/CJS dans
build.mjs. Conserver les plugins de rollup existants ; mettre à jour la configuration et le code pour réussir la CI."
- Fournir des journaux ou un lien vers les artefacts de la CI.
- Demander à OpenHands de répliquer localement (
npm run build) et de proposer des diffs minimaux.
3) Couverture des tests et durcissement
- Invite : "Augmenter la couverture pour
payments/service.py de 62 % à 85 % et plus. Ajouter des tests unitaires pour retry_charge, refund, webhook_signature. Ne pas modifier la logique métier à moins qu'un test ne révèle un bug."
- Laisser OpenHands générer des tests, les exécuter et les affiner.
4) Documentation et expérience développeur
- Invite : "Créer un
CONTRIBUTING.md et un DEVELOPMENT.md pour ce dépôt. Inclure la configuration de l'environnement, les scripts, les commandes de test et les directives de PR."
- Faites-lui vérifier les commandes en les exécutant réellement.
Garde-fous : Garder OpenHands utile et sûr
- Portée du répertoire : Pointez-le vers un dépôt ou un répertoire spécifique pour éviter les modifications accidentelles ailleurs.
- Protection des fichiers : Marquez les fichiers de configuration ou l'infrastructure critique comme étant en lecture seule lorsque cela est possible.
- Audit des commandes : Exiger une approbation pour les commandes destructives (par exemple,
rm -rf, réinitialisations de base de données).
- Hygiène des secrets : Ne jamais coller de clés API dans les invites. Utilisez des variables d'environnement et des journaux masqués.
- Accès au réseau : Si la navigation est activée, mettez-la en sandbox et enregistrez les appels sortants.
Modèles locaux vs cloud : Choisir ce qui vous convient
- Avantages : Raisonnement/codage solides, configuration minimale, itération rapide
- Inconvénients : Coût continu, considérations de gouvernance des données
- Avantages : Confidentialité, contrôle, prévisibilité des coûts
- Inconvénients : Demandes matérielles, qualité du modèle variable, plus de réglages nécessaires
Consultez les instructions officielles Local LLMs pour configurer les backends de modèle et les limites de mémoire.
Jeu d'équipe : Utiliser OpenHands dans un flux collaboratif
- Flux de travail axé sur les branches : Demandez à OpenHands de créer une branche de fonctionnalité et de pousser les modifications pour la revue de PR.
- Hygiène des commits : Demandez-lui de produire des commits atomiques avec des messages clairs et des numéros de problème de référence.
- Modèles de PR : Générez et appliquez des modèles de PR afin que les relecteurs sachent ce qui a changé et pourquoi.
- Propriétaires de code : Combinez avec CODEOWNERS pour acheminer les PR générées par l'IA vers les bons relecteurs.
Dépannage des problèmes courants
- Il se bloque ou boucle : Réduisez la portée. Demandez-lui d'expliquer sa prochaine étape. Fournissez un test en échec.
- Diffs désordonnés : Demandez un plan plus petit et échelonné : les tests d'abord, puis des modifications de code minimales.
- Mauvaises modifications de fichiers : Spécifiez les chemins exacts et rappelez-lui les limites.
- Réussit localement mais échoue en CI : Partagez les détails de l'environnement CI et les journaux ; faites-le répliquer avec un conteneur.
Conseils de performance et mouvements de puissance
- Contexte de démarrage à chaud : Demandez-lui de lire les fichiers clés d'abord (
README, package.json, fichiers de service principaux).
- Donnez-lui des scripts : Fournissez un
make test ou npm run verify afin qu'il puisse valider rapidement.
- Enseignez le domaine : Offrez un bref aperçu architectural ; cela rapporte en moins d'erreurs de logique.
- Appliquez le style : Pointez vers les configurations
.eslintrc, .prettierrc, black/ruff afin qu'il formate correctement.
- Utilisez des points de contrôle : Après chaque étape importante, demandez un résumé et les prochaines étapes pour le maintenir sur la bonne voie.
Scénario réel : Du rapport de bug au correctif en une heure
- Situation : Un bug de production laisse tomber des 500 non gérés sur des charges utiles JSON malformées dans l'API
orders.
- Votre invite : "Reproduire le 500 sur JSON malformé dans
orders POST. Ajouter la validation du schéma et renvoyer 400 avec les détails de l'erreur. Mettre à jour les tests pour couvrir les charges utiles malformées."
- Exécute l'API localement, reproduit l'erreur
- Ajoute une couche de validation et un gestionnaire d'erreurs
- Met à jour les tests et s'assure que la CI réussit
- Produit une PR compacte avec une entrée de changelog
Temps gagné : Vous vous êtes concentré sur l'analyse d'impact et le déploiement, tandis qu'OpenHands a géré l'échafaudage.
Intégrations qui suralimentent OpenHands
- Exécuteurs de tests : pytest, Jest, Vitest, JUnit
- Outils de construction : Vite, Webpack, Rollup, Babel
- Gestionnaires de paquets : npm, pnpm, yarn, pip/poetry
- Linters/formatteurs : ESLint, Prettier, black, ruff
- Conteneurs : Docker Compose pour la parité locale avec la CI
En standardisant ces outils, OpenHands peut raisonner sur votre pile de manière plus fiable et automatiser davantage la boucle de développement.
Au fait : Utiliser Sider.AI avec OpenHands
Score de pertinence : 8/10. Si vous utilisez OpenHands comme ingénieur IA, il vaut la peine de l'associer à un copilote de recherche et de rédaction pour les spécifications, les descriptions de PR et la documentation. Au fait, Sider.AI peut vous aider à rédiger rapidement des spécifications techniques, à résumer des RFC ou à transformer les journaux d'exécution d'OpenHands en journaux de modifications et notes de version propres. La combinaison réduit le changement de contexte : OpenHands gère les actions de code tandis que Sider.AI transforme les résultats en documents propres et destinés aux utilisateurs.
Liste de contrôle de sécurité, de confidentialité et de conformité
- Conservez les secrets dans les variables d'environnement ; n'intégrez jamais de clés dans les invites
- Examinez chaque modification générée par l'IA comme vous le feriez pour une PR d'un jeune développeur
- Enregistrez les commandes et les actions pour la vérifiabilité
- Épinglez les versions de la chaîne d'outils ; évitez les mises à niveau accidentelles dans les fichiers de verrouillage
- Si vous utilisez des LLM cloud, alignez-vous sur vos politiques de conservation des données
Quand ne pas utiliser OpenHands
- Conception d'algorithmes nouveaux sans tests solides ou échafaudage de spécifications
- Bases de code hautement réglementées sans processus de revue robuste
- Scripts jetables ponctuels où le codage manuel est plus rapide
Vos 60 premières minutes avec OpenHands : Un mini guide
- Minute 0–10 : Installez et lancez en utilisant le démarrage rapide officiel
- Minute 10–20 : Connectez votre dépôt ; demandez-lui de cartographier la structure du projet
- Minute 20–35 : Définissez un petit objectif testable ; approuvez son plan
- Minute 35–50 : Laissez-le implémenter et exécuter des tests ; poussez-le au besoin
- Minute 50–60 : Examinez les diffs, affinez et fusionnez dans une branche de fonctionnalité
Liens clés et prochaines étapes
- Documentation officielle "Start Building" et d'utilisation pour OpenHands : conseils, démarrage rapide et meilleures pratiques.
- Guide de configuration Local LLM : configurez et exécutez OpenHands entièrement sur votre machine.
- Procédure d'installation axée sur la communauté sur une VM : étapes d'installation réelles et un projet de démonstration rapide.
Points clés à retenir
- Encadrez les tâches comme des tickets avec des critères d'acceptation clairs.
- Gardez les itérations petites ; testez tôt et souvent.
- Utilisez des garde-fous et examinez les changements - traitez-le comme un jeune coéquipier.
- Choisissez le cloud pour la commodité, les modèles locaux pour la confidentialité.
- Associez-le à des outils de documentation (par exemple, Sider.AI) pour accélérer les spécifications et les notes de version.
FAQ
Q1:Comment puis-je installer et commencer à utiliser AI OpenHands rapidement ?
Utilisez le démarrage rapide officiel pour installer les prérequis, branchez un LLM pris en charge (cloud ou local) et lancez l'interface utilisateur pour connecter votre référentiel. La documentation "Start Building" fournit des instructions étape par étape avec des conseils de configuration.
Q2:Puis-je exécuter OpenHands avec un LLM local au lieu d'un modèle cloud ?
Oui. Suivez le guide Local LLMs pour configurer un backend de modèle local et ajuster les paramètres de contexte. Ceci est idéal pour les projets sensibles à la confidentialité ou pour éviter les coûts d'API.
Q3:Quelle est la meilleure façon d'inviter OpenHands pour les tâches de codage ?
Écrivez des invites comme des tickets concis : définissez l'objectif, référencez des fichiers spécifiques, définissez des limites et incluez des critères d'acceptation. Demandez-lui de créer ou d'exécuter des tests pour valider les progrès.
Q4:AI OpenHands est-il sûr à utiliser sur le code de production ?
Traitez-le comme un jeune développeur : utilisez des protections de branche, une revue de code et une CI pour valider les changements. Ajoutez des garde-fous pour les commandes et gardez les secrets hors des invites.
Q5:Comment OpenHands se compare-t-il à un assistant de code traditionnel ?
Contrairement aux outils qui ne font que discuter, OpenHands peut exécuter des commandes, modifier des fichiers et itérer de manière autonome dans votre dépôt. Il est conçu pour les tâches de bout en bout comme les fonctionnalités, le débogage et les tests.
