Como usar o AI OpenHands: Um guia prático para configuração, prompts e fluxos de trabalho do mundo real
Se você já desejou ter um desenvolvedor capaz para programar em par com você 24 horas por dia, 7 dias por semana, o AI OpenHands chega bem perto. É um "engenheiro de IA" de código aberto que pode ler seu repositório, escrever código, executar terminais, navegar por documentos e iterar — muito parecido com um desenvolvedor júnior que aprende rapidamente e trabalha incansavelmente. Mas o poder só se revela quando você o configura corretamente e aprende a direcioná-lo.
Este guia explica passo a passo como usar o AI OpenHands — desde a instalação até fluxos de trabalho avançados — para que você possa entregar mais rápido com confiança.
- Opções de instalação e início rápido
- Executando o OpenHands localmente ou com modelos de nuvem
- Melhores práticas para prompts, repositórios e tarefas
- Fluxos de trabalho comprovados para trabalho em recursos, depuração, testes e documentos
- Proteções, privacidade e colaboração
Vale a pena notar: O OpenHands está sendo ativamente desenvolvido pela equipe All Hands e pela comunidade. A documentação oficial é sua estrela guia para obter instruções e dicas atuais. Você também pode seguir guias práticos de instalação de profissionais que documentaram configurações locais e de VM. Para executar com modelos locais, a documentação também inclui orientação específica.
O que é o AI OpenHands — e por que usá-lo?
Pense no AI OpenHands como um colega de equipe de IA com um teclado. Ao contrário dos assistentes somente de bate-papo, o OpenHands pode:
- Abrir e ler arquivos de projeto
- Usar um terminal para executar comandos, testes e linters
- Editar código em arquivos e diretórios
- Navegar na web (dependendo da configuração)
- Propor e aplicar planos passo a passo
Isso o torna ideal para tarefas como implementar recursos, corrigir bugs, escrever testes, criar documentos, refatorar e modernizar bases de código. Em vez de ficar alternando prompts e copiar/colar, você dá ao OpenHands um objetivo e o deixa iterar, com você supervisionando seus movimentos.
Início Rápido: A maneira mais rápida de usar o OpenHands
Existem várias maneiras de começar. Sua escolha depende se você deseja usar um LLM na nuvem ou executar tudo localmente.
Opção A: Usar um LLM na Nuvem (mais fácil)
- Siga os documentos oficiais "Start Building" e "Getting Started" para instalar e executar o aplicativo. Normalmente, você irá:
- Instalar os pré-requisitos (Docker, Node, Python, Git dependendo do caminho)
- Fornecer uma chave de API para um modelo de nuvem suportado (por exemplo, OpenAI, Anthropic ou outros que o projeto suporta no momento)
- Iniciar a interface OpenHands e conectar seu repositório
Este caminho permite que você se torne produtivo rapidamente com sobrecarga computacional mínima.
Opção B: Executar o OpenHands com um LLM Local
- Se você preferir manter o código e os prompts fora da nuvem ou quiser evitar custos de API, use o guia de LLMs locais na documentação oficial.
- Configurar um modelo local compatível (via Ollama ou outros backends suportados no momento)
- Configurar endpoints de modelo e limites de contexto
- Garantir que sua máquina tenha VRAM/CPU e espaço em disco adequados
Opção C: Implantar em uma VM
- Se você precisar de um ambiente dedicado, os profissionais documentaram como ativar o OpenHands em uma VM e construir um aplicativo em minutos. Isso é útil para equipes que desejam uma instância de engenheiro de IA estável e compartilhada.
Primeira execução: Configuração do projeto e enquadramento da tarefa
O OpenHands se destaca quando consegue ver seu código. Comece por:
- Abrir o repositório no qual você deseja que ele trabalhe.
- Executar ou indexar o projeto para que o OpenHands possa mapear a estrutura.
- Dar-lhe um objetivo claro com restrições.
Bom exemplo de enquadramento de tarefa:
- "Adicionar redefinição de senha do usuário ao serviço
auth usando links de e-mail baseados em token. Usar o módulo mailer existente. Adicionar testes de unidade para geração e expiração de token. Não alterar o esquema de dados do usuário."
Por que isso funciona:
- Ele nomeia o componente, escopo, dependências e limites. Quanto mais claro você for, melhor o OpenHands planeja e executa.
Como escrever prompts eficazes para OpenHands
Pense em prompts como tickets concisos. Os melhores:
- Definem o resultado: "Implementar X com restrições Y"
- Referenciam arquivos, módulos ou testes: "Ver
auth/routes.py e tests/test_auth.py"
- Indicam restrições: "Sem alterações no esquema do BD; manter as interfaces existentes"
- Incluem critérios de aceitação: "Os testes devem passar:
pytest -k password_reset"
Modelo que você pode reutilizar:
Objetivo: <O que você deseja construir ou corrigir>
Contexto: <Arquivos relevantes, restrições conhecidas, serviços externos>
Aceitação: <Como é a aprovação: testes, endpoints, métricas>
Limites: <O que não alterar ou abordagens a evitar>
Ferramentas: <Comandos que pode executar, scripts ou fontes de dados>
Fluxo de trabalho principal: Planejar → Executar → Verificar → Refinar
O OpenHands geralmente propõe um plano de várias etapas. Veja como orientá-lo:
- Aprove ou ajuste seu plano antecipadamente. Force-o a executar os testes primeiro para definir as falhas de linha de base.
- Peça-lhe para criar ou atualizar um teste para definir o sucesso e, em seguida, implementar o código.
- Peça-lhe para executar o conjunto de testes e linters com frequência.
- Se ele travar, adicione mais contexto: nomes de arquivos, stack traces ou logs.
Dica profissional: Incentive pequenas alterações do tamanho de um PR, em vez de edições monolíticas. Isso ajuda na capacidade de revisão e reversão.
Exemplos de fluxos de trabalho que você pode copiar
1) Implementação de recursos
- Prompt: "Adicionar exportação de CSV à página
orders. Usar paginação do lado do servidor, transmitir resultados via text/csv. Adicionar botão Export em OrdersTable.jsx e endpoint em routes/orders.ts. Incluir testes para paginação e cabeçalhos."
- Verifica o repositório; rascunha o plano
- Adiciona endpoint e botão do cliente
- Escreve testes e os executa
- Você supervisiona, aprova as alterações e mescla quando estiver tudo certo.
2) Depurando uma build com falha
- Prompt: "O CI está falhando no Node 20. Corrigir erros de importação ESM/CJS em
build.mjs. Manter os plugins rollup existentes; atualizar a configuração e o código para passar no CI."
- Forneça logs ou link para artefatos de CI.
- Peça ao OpenHands para replicar localmente (
npm run build) e propor diffs mínimos.
3) Cobertura de teste e fortalecimento
- Prompt: "Aumentar a cobertura para
payments/service.py de 62% para 85%+. Adicionar testes de unidade para retry_charge, refund, webhook_signature. Não modificar a lógica de negócios, a menos que o teste exponha um bug."
- Deixe o OpenHands gerar testes, executá-los e refiná-los.
4) Documentação e experiência do desenvolvedor
- Prompt: "Criar um
CONTRIBUTING.md e DEVELOPMENT.md para este repositório. Incluir configuração de ambiente, scripts, comandos de teste e diretrizes de PR."
- Peça-lhe para verificar os comandos executando-os realmente.
Proteções: Mantenha o OpenHands útil e seguro
- Escopo do diretório: Aponte-o para um repositório ou diretório específico para evitar edições acidentais em outros lugares.
- Proteção de arquivos: Marque arquivos de configuração ou infraestrutura crítica como somente leitura, sempre que possível.
- Auditoria de comandos: Exija aprovação para comandos destrutivos (por exemplo,
rm -rf, redefinições de banco de dados).
- Higiene de segredos: Nunca cole chaves de API em prompts. Use variáveis de ambiente e logs mascarados.
- Acesso à rede: Se a navegação estiver habilitada, coloque-a em sandbox e registre as chamadas de saída.
Modelos locais vs. Modelos de nuvem: Escolhendo o que é certo para você
- Prós: Raciocínio/codificação fortes, configuração mínima, iteração rápida
- Contras: Custo contínuo, considerações sobre governança de dados
- Prós: Privacidade, controle, previsibilidade de custos
- Contras: Demandas de hardware, qualidade do modelo varia, mais ajustes necessários
Consulte as instruções oficiais de LLMs locais para configurar backends de modelo e limites de memória.
Trabalho em equipe: Usando o OpenHands em um fluxo colaborativo
- Fluxo de trabalho branch-first: Faça com que o OpenHands crie uma branch de recurso e envie as alterações para revisão de PR.
- Higiene de commit: Peça-lhe para produzir commits atômicos com mensagens claras e referenciar números de issue.
- Modelos de PR: Gere e aplique modelos de PR para que os revisores saibam o que mudou e por quê.
- Proprietários de código: Combine com CODEOWNERS para encaminhar PRs gerados por IA para os revisores certos.
Solução de problemas comuns
- Ele fica preso ou em loop: Diminua o escopo. Peça-lhe para explicar sua próxima etapa. Forneça um teste com falha.
- Diffs confusos: Solicite um plano menor e organizado — testes primeiro, depois alterações mínimas de código.
- Edições de arquivos erradas: Especifique os caminhos exatos e lembre-o dos limites.
- Passando localmente, mas falhando no CI: Compartilhe os detalhes do ambiente de CI e os logs; peça-lhe para replicar com um contêiner.
Dicas de desempenho e jogadas de poder
- Contexto de warm-start: Peça-lhe para ler os arquivos-chave primeiro (
README, package.json, arquivos de serviço principais).
- Dê-lhe scripts: Forneça um
make test ou npm run verify para que ele possa validar rapidamente.
- Ensine o domínio: Ofereça uma breve visão geral da arquitetura; vale a pena em menos erros de lógica.
- Aplique o estilo: Aponte para as configurações
.eslintrc, .prettierrc, black/ruff para que ele formate corretamente.
- Use checkpoints: Após cada marco, peça um resumo e os próximos passos para mantê-lo no caminho certo.
Cenário do mundo real: Do relatório de bug ao patch em uma hora
- Situação: Um bug de produção derruba 500s não tratados em payloads JSON malformados na API
orders.
- Seu prompt: "Reproduzir o 500 em JSON malformado em
orders POST. Adicionar validação de esquema e retornar 400 com detalhes do erro. Atualizar os testes para cobrir payloads malformados."
- Executa a API localmente, reproduz o erro
- Adiciona uma camada de validação e um manipulador de erros
- Atualiza os testes e garante que o CI passe
- Produz um PR compacto com uma entrada de changelog
Tempo economizado: Você se concentrou na análise de impacto e lançamento, enquanto o OpenHands lidou com o scaffolding.
Integrações que turbinam o OpenHands
- Executores de teste: pytest, Jest, Vitest, JUnit
- Ferramentas de build: Vite, Webpack, Rollup, Babel
- Gerenciadores de pacotes: npm, pnpm, yarn, pip/poetry
- Linters/formatadores: ESLint, Prettier, black, ruff
- Contêineres: Docker Compose para paridade local com CI
Ao padronizar essas ferramentas, o OpenHands pode raciocinar sobre sua pilha de forma mais confiável e automatizar mais o loop de desenvolvimento.
A propósito: Usando o Sider.AI junto com o OpenHands
Pontuação de relevância: 8/10. Se você estiver usando o OpenHands como seu engenheiro de IA, vale a pena combiná-lo com um copiloto de pesquisa e redação para especificações, descrições de PR e documentação. A propósito, o Sider.AI pode ajudá-lo a criar rapidamente especificações técnicas, resumir RFCs ou transformar logs de execução do OpenHands em changelogs e notas de lançamento limpos. A combinação reduz a troca de contexto: o OpenHands lida com ações de código enquanto o Sider.AI transforma os resultados em documentos limpos e voltados para o usuário.
Lista de verificação de segurança, privacidade e conformidade
- Mantenha os segredos em variáveis de ambiente; nunca incorpore chaves em prompts
- Revise cada alteração gerada por IA como faria com o PR de um desenvolvedor júnior
- Registre comandos e ações para fins de auditoria
- Fixe as versões da toolchain; evite atualizações acidentais em lockfiles
- Se estiver usando LLMs na nuvem, alinhe-se com suas políticas de retenção de dados
Quando não usar o OpenHands
- Design de algoritmo inovador sem testes fortes ou scaffolding de especificação
- Bases de código altamente regulamentadas sem um processo de revisão robusto
- Scripts descartáveis únicos onde a codificação manual é mais rápida
Seus primeiros 60 minutos com o OpenHands: Um mini guia
- Minuto 0–10: Instale e inicie usando o Quickstart oficial
- Minuto 10–20: Conecte seu repositório; peça-lhe para mapear a estrutura do projeto
- Minuto 20–35: Defina um objetivo pequeno e testável; aprove seu plano
- Minuto 35–50: Deixe-o implementar e executar testes; incentive conforme necessário
- Minuto 50–60: Revise os diffs, refine e mescle em uma branch de recurso
Links importantes e próximos passos
- Documentos oficiais "Start Building" e de uso para OpenHands: dicas, quickstart e melhores práticas.
- Guia de configuração de LLM local: configure e execute o OpenHands inteiramente em sua máquina.
- Passo a passo de instalação orientado pela comunidade em uma VM: etapas de instalação do mundo real e um projeto de demonstração rápida.
Conclusões
- Enquadre as tarefas como tickets com critérios de aceitação claros.
- Mantenha as iterações pequenas; teste cedo e com frequência.
- Use proteções e revise as alterações — trate-o como um colega de equipe júnior.
- Escolha a nuvem para conveniência, modelos locais para privacidade.
- Combine com ferramentas de documentação (por exemplo, Sider.AI) para acelerar especificações e notas de lançamento.
FAQ
P1: Como instalo e começo a usar o AI OpenHands rapidamente?
Use o quickstart oficial para instalar os pré-requisitos, conecte um LLM suportado (nuvem ou local) e inicie a interface do usuário para conectar seu repositório. Os documentos "Start Building" fornecem instruções passo a passo com dicas de configuração.
P2: Posso executar o OpenHands com um LLM local em vez de um modelo de nuvem?
Sim. Siga o guia de LLMs locais para configurar um backend de modelo local e ajustar as configurações de contexto. Isso é ideal para projetos sensíveis à privacidade ou para evitar custos de API.
P3: Qual é a melhor maneira de solicitar ao OpenHands tarefas de codificação?
Escreva prompts como tickets concisos: defina o objetivo, referencie arquivos específicos, defina limites e inclua critérios de aceitação. Peça-lhe para criar ou executar testes para validar o progresso.
P4: O AI OpenHands é seguro para usar em código de produção?
Trate-o como um desenvolvedor júnior: use proteções de branch, revisão de código e CI para validar as alterações. Adicione proteções para comandos e mantenha os segredos fora dos prompts.
P5: Como o OpenHands se compara a um assistente de código tradicional?
Ao contrário das ferramentas somente de bate-papo, o OpenHands pode executar comandos, editar arquivos e iterar autonomamente dentro do seu repositório. Ele foi criado para tarefas de ponta a ponta, como recursos, depuração e testes.
