Com utilitzar AI OpenHands: Una guia pràctica per a la configuració, els prompts i els fluxos de treball del món real
Si alguna vegada has desitjat que un desenvolupador capaç pogués programar amb tu 24 hores al dia, 7 dies a la setmana, AI OpenHands s'hi acosta sorprenentment. És un "enginyer d'IA" de codi obert que pot llegir el teu repositori, escriure codi, executar terminals, consultar documents i iterar, de manera molt semblant a un desenvolupador junior que aprèn ràpidament i treballa incansablement. Però el poder només es fa evident quan el configureu correctament i apreneu a dirigir-lo.
Aquesta guia us mostra pas a pas com utilitzar AI OpenHands, des de la instal·lació fins als fluxos de treball avançats, perquè pugueu lliurar més ràpidament amb confiança.
- Opcions d'instal·lació i inici ràpid
- Execució d'OpenHands localment o amb models al núvol
- Millors pràctiques per a prompts, repositoris i tasques
- Fluxos de treball provats per a treball de funcions, depuració, proves i documentació
- Proteccions, privadesa i col·laboració
Val la pena destacar: OpenHands està sent desenvolupat activament per l'equip d'All Hands i la comunitat. La documentació oficial és la vostra estrella polar per a les instruccions i consells actuals. També podeu seguir guies d'instal·lació pràctiques de professionals que han documentat configuracions locals i de màquines virtuals (VM). Per a l'execució amb models locals, la documentació inclou orientació específica.
Què és AI OpenHands i per què utilitzar-lo?
Penseu en AI OpenHands com un company d'equip d'IA amb un teclat. A diferència dels assistents només de xat, OpenHands pot:
- Obrir i llegir fitxers de projecte
- Utilitzar un terminal per executar ordres, proves i linters
- Editar codi a través de fitxers i directoris
- Navegar per la web (depenent de la configuració)
- Proposar i aplicar plans pas a pas
Això el fa ideal per a tasques com implementar funcions, corregir errors, escriure proves, crear documents, refactoritzar i modernitzar bases de codi. En lloc de fer malabars amb prompts i copiar/enganxar, doneu a OpenHands un objectiu i deixeu que iteri, amb vosaltres supervisant els seus moviments.
Inici ràpid: La manera més ràpida d'utilitzar OpenHands
Hi ha diverses maneres de començar. La vostra elecció depèn de si voleu utilitzar un LLM al núvol o executar tot localment.
Opció A: Utilitzar un LLM al núvol (més fàcil)
- Seguiu els documents oficials "Start Building" i "Getting Started" per instal·lar i executar l'aplicació. Normalment:
- Instal·lar requisits previs (Docker, Node, Python, Git depenent del camí)
- Proporcionar una clau API per a un model al núvol compatible (p. ex., OpenAI, Anthropic o altres que el projecte admeti en el moment)
- Llançar la interfície d'OpenHands i connectar el vostre repositori
Aquest camí us permet ser productius ràpidament amb una sobrecàrrega de càlcul mínima.
Opció B: Executar OpenHands amb un LLM local
- Si preferiu mantenir el codi i els prompts fora del núvol o voleu evitar els costos de l'API, utilitzeu la guia de LLMs locals a la documentació oficial.
- Configurar un model local compatible (mitjançant Ollama o altres backends compatibles en el moment)
- Configurar els punts finals del model i els límits de context
- Assegurar-vos que la vostra màquina tingui suficient VRAM/CPU i espai en disc
Opció C: Desplegar a una VM
- Si necessiteu un entorn dedicat, els professionals han documentat com fer girar OpenHands en una VM i construir una aplicació en minuts. Això és útil per als equips que volen una instància d'enginyer d'IA estable i compartida.
Primera execució: Configuració del projecte i enquadrament de la tasca
OpenHands brilla quan pot veure el vostre codi. Comenceu per:
- Obrir el repositori en el qual voleu que treballi.
- Executar o indexar el projecte perquè OpenHands pugui mapejar l'estructura.
- Donar-li un objectiu clar amb restriccions.
Bon exemple d'enquadrament de tasca:
- "Afegiu el restabliment de contrasenya d'usuari al servei
auth utilitzant enllaços de correu electrònic basats en testimoni. Utilitzeu el mòdul mailer existent. Afegiu proves unitàries per a la generació i caducitat de testimoni. No canvieu l'esquema de dades d'usuari."
Per què funciona:
- Anomena el component, l'àmbit, les dependències i les fronteres. Com més clar sigueu, millor planifica i executa OpenHands.
Com escriure prompts efectius per a OpenHands
Penseu en els prompts com a tiquets concisos. Els millors:
- Defineixen el resultat: "Implementeu X amb restriccions Y"
- Fan referència a fitxers, mòduls o proves: "Vegeu
auth/routes.py i tests/test_auth.py"
- Estableixen restriccions: "Sense canvis d'esquema de DB; manteniu les interfícies existents"
- Inclouen criteris d'acceptació: "Les proves haurien de passar:
pytest -k password_reset"
Plantilla que podeu reutilitzar:
Objectiu: <Què voleu construir o arreglar>
Context: <Fitxers rellevants, restriccions conegudes, serveis externs>
Acceptació: <Com es veu l'aprovació: proves, punts finals, mètriques>
Fronteres: <Què no s'ha de canviar o enfocaments a evitar>
Eines: <Comandes que pot executar, scripts o fonts de dades>
Flux de treball bàsic: Planificar → Executar → Verificar → Refinar
OpenHands normalment proposa un pla de diversos passos. A continuació, s'explica com guiar-lo:
- Aproveu o ajusteu el seu pla aviat. Forceu-lo a executar proves primer per establir les fallades de base.
- Demaneu-li que creï o actualitzi una prova per definir l'èxit i, a continuació, implementeu el codi.
- Feu que executi la suite de proves i els linters amb freqüència.
- Si s'encalla, afegiu més context: noms de fitxers, traces de pila o registres.
Consell professional: Animeu canvis petits de la mida d'una PR en lloc d'edicions monolítiques. Això ajuda amb la revisabilitat i la reversió.
Exemples de fluxos de treball que podeu copiar
1) Implementació de funcions
- Prompt: "Afegiu l'exportació CSV a la pàgina
orders. Utilitzeu la paginació del costat del servidor, transmeteu els resultats mitjançant text/csv. Afegiu el botó Export a OrdersTable.jsx i el punt final a routes/orders.ts. Incloeu proves per a la paginació i les capçaleres."
- Escaneja el repositori; elabora el pla
- Afegeix el punt final i el botó del client
- Escriu proves i les executa
- Superviseu, aproveu els canvis i fusioneu un cop estigui tot correcte.
2) Depuració d'una compilació fallida
- Prompt: "CI està fallant a Node 20. Corregiu els errors d'importació ESM/CJS a
build.mjs. Manteniu els plugins rollup existents; actualitzeu la configuració i el codi per passar CI."
- Proporcioneu registres o enllaç a artefactes de CI.
- Demaneu a OpenHands que repliqui localment (
npm run build) i proposi diffs mínims.
3) Cobertura de proves i enduriment
- Prompt: "Augmenteu la cobertura per a
payments/service.py del 62% al 85%+. Afegiu proves unitàries per a retry_charge, refund, webhook_signature. No modifiqueu la lògica de negoci tret que la prova exposi un error."
- Deixeu que OpenHands generi proves, les executi i les refini.
4) Documentació i experiència del desenvolupador
- Prompt: "Creeu un fitxer
CONTRIBUTING.md i DEVELOPMENT.md per a aquest repositori. Incloeu la configuració de l'entorn, els scripts, les ordres de prova i les directrius de PR."
- Feu que verifiqui les ordres executant-les realment.
Proteccions: Mantingueu OpenHands útil i segur
- Àmbit del directori: Apunteu-lo a un repositori o directori específic per evitar edicions accidentals en altres llocs.
- Protecció de fitxers: Marqueu els fitxers de configuració o la infraestructura crítica com a només lectura sempre que sigui possible.
- Auditoria d'ordres: Requereix l'aprovació per a ordres destructives (p. ex.,
rm -rf, restabliments de la base de dades).
- Higiene de secrets: No enganxeu mai claus API als prompts. Utilitzeu variables d'entorn i registres emmascarats.
- Accés a la xarxa: Si la navegació està habilitada, poseu-la en un sandbox i registreu les crides de sortida.
Models locals vs. Models al núvol: Triar el que és adequat per a vosaltres
- Avantatges: Raonament/codificació forts, configuració mínima, iteració ràpida
- Desavantatges: Cost continu, consideracions de governança de dades
- Avantatges: Privadesa, control, predictibilitat de costos
- Desavantatges: Exigències de hardware, la qualitat del model varia, es necessita més ajust
Consulteu les instruccions oficials de LLMs locals per configurar els backends del model i els límits de memòria.
Joc en equip: Utilitzar OpenHands en un flux col·laboratiu
- Flux de treball primer de branca: Feu que OpenHands creï una branca de funcions i enviï els canvis per a la revisió de la PR.
- Higiene de commit: Demaneu-li que produeixi commits atòmics amb missatges clars i que faci referència als números de problema.
- Plantilles de PR: Genereu i apliqueu plantilles de PR perquè els revisors sàpiguen què ha canviat i per què.
- Propietaris del codi: Combineu amb CODEOWNERS per encaminar les PR generades per IA als revisors adequats.
Resolució de problemes comuns
- S'encalla o entra en bucle: Reduïu l'àmbit. Demaneu-li que expliqui el seu següent pas. Proporcioneu una prova fallida.
- Diffs desordenats: Sol·liciteu un pla més petit i per etapes: proves primer, després canvis de codi mínims.
- Edicions de fitxers incorrectes: Especifiqueu camins exactes i recordeu-li les fronteres.
- Passa localment però falla a CI: Compartiu detalls de l'entorn de CI i registres; feu que repliqui amb un contenidor.
Consells de rendiment i moviments potents
- Context d'inici calent: Demaneu-li que llegeixi primer els fitxers clau (
README, package.json, fitxers de servei principals).
- Doneu-li scripts: Proporcioneu un
make test o npm run verify perquè pugui validar ràpidament.
- Ensenyeu el domini: Oferiu una breu visió general arquitectural; val la pena tenir menys errors de lògica.
- Apliqueu l'estil: Apunteu a les configuracions
.eslintrc, .prettierrc, black/ruff perquè format correctament.
- Utilitzeu punts de control: Després de cada fita, demaneu un resum i els següents passos per mantenir-lo en el bon camí.
Escenari del món real: De l'informe d'errors al pegat en una hora
- Situació: Un error de producció deixa caure 500 sense gestionar en càrregues útils JSON mal formades a l'API
orders.
- El vostre prompt: "Reproduïu el 500 en JSON mal format a
orders POST. Afegiu la validació d'esquema i retorneu 400 amb detalls de l'error. Actualitzeu les proves per cobrir les càrregues útils mal formades."
- Executa l'API localment, reprodueix l'error
- Afegeix una capa de validació i un gestor d'errors
- Actualitza les proves i garanteix que CI passi
- Produeix una PR compacta amb una entrada de registre de canvis
Temps estalviat: Us heu centrat en l'anàlisi d'impacte i el desplegament, mentre que OpenHands ha gestionat l'estructura.
Integracions que sobrealimenten OpenHands
- Executors de proves: pytest, Jest, Vitest, JUnit
- Eines de construcció: Vite, Webpack, Rollup, Babel
- Gestors de paquets: npm, pnpm, yarn, pip/poetry
- Linters/formatadors: ESLint, Prettier, black, ruff
- Contenidors: Docker Compose per a la paritat local amb CI
En estandarditzar aquestes eines, OpenHands pot raonar sobre la vostra pila de manera més fiable i automatitzar més el bucle de desenvolupament.
Per cert: Utilitzar Sider.AI juntament amb OpenHands
Puntuació de rellevància: 8/10. Si utilitzeu OpenHands com el vostre enginyer d'IA, val la pena combinar-lo amb un copilot de recerca i redacció per a especificacions, descripcions de PR i documentació. Per cert, Sider.AI us pot ajudar a redactar ràpidament especificacions tècniques, resumir RFCs o transformar els registres d'execució d'OpenHands en registres de canvis i notes de llançament nets. La combinació redueix el canvi de context: OpenHands gestiona les accions de codi mentre que Sider.AI converteix els resultats en documents nets orientats a l'usuari.
Llista de verificació de seguretat, privadesa i compliment
- Mantingueu els secrets a les variables d'entorn; no incrusteu mai claus als prompts
- Reviseu cada canvi generat per IA com ho faríeu amb la PR d'un desenvolupador junior
- Registreu les ordres i les accions per a l'auditabilitat
- Fixeu les versions de la cadena d'eines; eviteu les actualitzacions accidentals als fitxers de bloqueig
- Si utilitzeu LLMs al núvol, alineeu-vos amb les vostres polítiques de retenció de dades
Quan no utilitzar OpenHands
- Disseny d'algorismes nous sense proves sòlides o estructures d'especificacions
- Bases de codi altament regulades sense un procés de revisió robust
- Scripts d'un sol ús on la codificació manual és més ràpida
Els vostres primers 60 minuts amb OpenHands: Un mini manual
- Minut 0–10: Instal·leu i executeu utilitzant l'inici ràpid oficial
- Minut 10–20: Connecteu el vostre repositori; demaneu-li que mapegi l'estructura del projecte
- Minut 20–35: Definiu un objectiu petit i provable; aproveu el seu pla
- Minut 35–50: Deixeu que implementi i executi proves; impulseu-lo segons sigui necessari
- Minut 50–60: Reviseu els diffs, refineu i fusioneu en una branca de funcions
Enllaços clau i passos següents
- Documentació oficial "Start Building" i d'ús per a OpenHands: consells, inici ràpid i millors pràctiques.
- Guia de configuració de LLM local: configureu i executeu OpenHands completament a la vostra màquina.
- Recorregut d'instal·lació impulsat per la comunitat en una VM: passos d'instal·lació del món real i un projecte de demostració ràpid.
Conclusions
- Enquadreu les tasques com a tiquets amb criteris d'acceptació clars.
- Mantingueu les iteracions petites; proveu aviat i sovint.
- Utilitzeu proteccions i reviseu els canvis; tracteu-lo com un company d'equip junior.
- Trieu el núvol per comoditat, els models locals per privadesa.
- Combineu amb eines de documentació (p. ex., Sider.AI) per accelerar les especificacions i les notes de llançament.
FAQ
Q1:Com instal·lo i començo a utilitzar AI OpenHands ràpidament?
Utilitzeu l'inici ràpid oficial per instal·lar els requisits previs, connecteu un LLM compatible (al núvol o local) i llançeu la IU per connectar el vostre repositori. La documentació "Start Building" proporciona instruccions pas a pas amb consells de configuració.
Q2:Puc executar OpenHands amb un LLM local en lloc d'un model al núvol?
Sí. Seguiu la guia de LLMs locals per configurar un backend de model local i ajustar la configuració del context. Això és ideal per a projectes sensibles a la privadesa o per evitar costos d'API.
Q3:Quina és la millor manera de demanar a OpenHands tasques de codificació?
Escriviu prompts com a tiquets concisos: definiu l'objectiu, feu referència a fitxers específics, establiu fronteres i incloeu criteris d'acceptació. Demaneu-li que creï o executi proves per validar el progrés.
Q4:És segur utilitzar AI OpenHands en codi de producció?
Tracteu-lo com un desenvolupador junior: utilitzeu proteccions de branca, revisió de codi i CI per validar els canvis. Afegiu proteccions per a les ordres i mantingueu els secrets fora dels prompts.
Q5:Com es compara OpenHands amb un assistent de codi tradicional?
A diferència de les eines només de xat, OpenHands pot executar ordres, editar fitxers i iterar de manera autònoma dins del vostre repositori. Està creat per a tasques d'extrem a extrem com ara funcions, depuració i proves.
