OpenHands: um agente desenvolvedor baseado em modelo local

#O que ele faz, concretamente

Você descreve uma tarefa em francês. Ele inspeciona o repositório, elabora um plano e depois age em um ciclo: executar um comando, ler o resultado, modificar um arquivo, executar os testes novamente, ler a falha, corrigir. Esse ciclo é o produto. Estamos mais perto de um estagiário com um terminal do que de um preenchimento automático.

Isso traz consequências. Cada iteração é uma geração completa sobre um contexto que cresce: uma tarefa em dez etapas custa dez prompts longos. E como o agente age em vez de sugerir, seu campo de ação abrange tudo a que ele tem acesso — o que explica por que o sandbox faz parte do projeto, e não das configurações.

#O projeto em 2026: Agent Canvas

OpenHands era chamado OpenDevin no seu lançamento, antes de assumir o nome atual. O repositório, mantido pela All Hands AI, está licenciado sob MIT e ultrapassou 89.000 estrelas no GitHub no verão de 2026. O projeto também se ampliou: não se apresenta mais apenas como um agente autônomo isolado, mas como 'o centro de controle auto-hospedado para agentes de código e automações', capaz de controlar tanto OpenHands quanto Claude Code, Codex ou Gemini por meio de uma única interface.

Na prática, a oferta se estruturou em vários componentes: Agent Canvas (a interface de controle), um Software Agent SDK para construir seus próprios agentes, um Agent Server e um servidor de automação para tarefas agendadas. A antiga interface local autônoma foi descontinuada em favor dessa arquitetura modular; o princípio permanece o mesmo para o uso local descrito aqui — um agente que atua em um sandbox conteinerizado —, mas os nomes dos componentes e o comando de inicialização podem variar entre diferentes documentações antigas, inclusive aquela que você ainda encontrará às vezes indexada sob o nome OpenDevin.

#A exigência quanto ao modelo, sem rodeios

Duas capacidades contam mais que os resultados de benchmark: a chamada de ferramentas no formato exato esperado e a estabilidade em contexto longo, pois o agente relê um histórico crescente a cada etapa. Um modelo excelente para escrever uma função a partir de um prompt pode ser inutilizável em loop. Modelos orientados a código geralmente superam modelos de conversa do mesmo tamanho nesse exercício.

A documentação oficial do projeto mudou sua recomendação ao longo de 2026: agora recomenda Qwen3.6-35B-A3B como primeiro modelo local a experimentar, um modelo MoE (mistura de especialistas) projetado para programação com agentes, com um contexto amplo e disponível via LM Studio, Ollama, vLLM e SGLang. A vantagem de um MoE aqui é direta: apenas 3 bilhões de parâmetros são ativados por token, apesar dos 35 bilhões de pesos totais, o que torna a geração significativamente mais rápida do que a de um modelo denso de tamanho comparável, com uma necessidade de VRAM mais próxima da de um modelo de 14B do que da de um modelo denso de 35B.

#Executar localmente

1. 01
   Servir um modelo

   Em um endpoint compatível com OpenAI, com a variável OLLAMA_CONTEXT_LENGTH aumentada para pelo menos 22.000 (32.768 recomendado) se você usar o Ollama. Essa é a etapa que costuma ser pulada, o que gera agentes que esquecem seu próprio plano.
2. 02
   Iniciar a aplicação na configuração contêinerizada

   Ela precisa de um mecanismo de contêineres (Docker Desktop ou Docker Engine): o shell do agente roda ali, não na sua máquina host.
3. 03
   Direcioná-lo para seu endpoint local

   Com uma chave de API fictícia (por exemplo, local-llm) e uma URL de base acessível a partir do contêiner — no Docker Desktop, http://host.docker.internal:PORT/v1 em vez de localhost, que indicaria o próprio contêiner. Só declare suporte a chamadas de ferramentas se o modelo realmente for capaz de realizá-las.
4. 04
   Montar um único repositório

   Idealmente, um clone descartável, em uma branch que você pode excluir sem preocupação.
5. 05
   Começar com uma tarefa pequena e verificável

   Corrija este teste que está falhando, adicione este parâmetro, atualize esta configuração. Depois, revise o diff.

• Servir um modelo com contexto longo
• Fazer um modelo local revisar código
• Cline: o agente de código integrado ao editor
• O kit QuelLLM para montar um agente local
• Documentação oficial: modelos locais com OpenHands
• Repositório oficial do OpenHands no GitHub
• Revisão independente do OpenHands (2026)

#O custo real de uma tarefa

Uma tarefa executada por um agente não exige uma única chamada ao modelo, mas uma sequência de chamadas, cada uma com um contexto mais longo que o anterior, pois o histórico se acumula. Para uma tarefa que leva dez iterações, se cada etapa adiciona, em média, 800 tokens ao histórico, a décima chamada já relê vários milhares de tokens de contexto antes mesmo de produzir sua resposta. No processamento local, o tempo de leitura do prompt (o “prefill”) se soma ao tempo de geração a cada rodada, o que explica por que um agente local usando um modelo de 32 bilhões de parâmetros leva minutos por tarefa, e não segundos como uma completação convencional.

É a contrapartida de não pagar uma fatura de API: o custo não desaparece, ele se transfere para a sua placa de vídeo e o seu tempo de espera. Em uma tarefa mal especificada que desencadeia vinte iterações porque o agente fica andando em círculos, essa transferência de custo logo sai mais cara, em eletricidade e tempo, do que uma chamada de API equivalente.

#Um exemplo concreto, para fixar as ideias

Vamos considerar uma tarefa realista: “o teste test_export_csv está falhando desde o último commit, corrija-o”. Em um modelo da classe de 32 bilhões, o fluxo típico leva de cinco a oito iterações: leitura do teste e da mensagem de falha, abertura do arquivo-fonte em questão, hipótese sobre a causa, modificação, nova execução do teste, leitura do novo resultado, ajuste se necessário. Cada iteração relê o histórico completo das anteriores, o que torna a janela de contexto decisiva: com apenas 8.000 tokens, o agente perde o fio após três ou quatro etapas e retoma hipóteses já descartadas.

Em um modelo de 7 a 8 bilhões de parâmetros, a mesma tarefa costuma falhar de outra maneira: o teste é identificado corretamente, mas o comando para executá-lo novamente está malformado, ou o modelo edita um arquivo próximo com um nome semelhante. Não se trata de erros de configuração — é o limite de capacidade do modelo diante do formato estrito exigido pelo ciclo ferramenta-resultado-decisão, independentemente da qualidade do prompt de sistema. É também por isso que as pontuações publicadas em benchmarks de completação de código não dizem muita coisa aqui: um modelo com uma pontuação alta na geração de uma função isolada pode continuar incapaz de encadear dez chamadas de ferramentas coerentes sem perder o rumo, porque a correlação entre essas duas habilidades varia conforme a maneira como o modelo foi treinado.

#A segurança não é opcional

Nenhum segredo no ambiente

O agente lê seu próprio ambiente e pode exibi-lo.

Uma branch descartável e um clone de trabalho

Nunca sua cópia de trabalho com modificações não validadas.

Acesso de rede restrito

Um agente que pode se conectar a qualquer destino pode exfiltrar tudo o que leu.

Todo conteúdo recuperado é hostil por padrão

A descrição de um ticket ou um arquivo README podem conter instruções destinadas ao agente: o mecanismo é detalhado no nosso guia sobre injeção de prompt.

Reler cada diff

« Os testes passam » significa que os testes passam, não que a modificação está correta.

#Quando um assistente é melhor que um agente

Resumindo, o OpenHands executado localmente não é um gadget nem um substituto universal: é uma ferramenta a ser reservada a máquinas que realmente conseguem acomodar um modelo com 27 bilhões de parâmetros ou mais e um contexto de 32.000 tokens, e a tarefas suficientemente delimitadas para que um teste automatizado ou uma revisão rápida baste para avaliar o resultado. Abaixo desse limiar de hardware, um assistente conversacional tradicional com o arquivo aberto continua mais rápido e mais confiável do que um agente que fica em loop sem nunca convergir.

#FAQ