OpenHands: o agente open source de codificação com IA explicado
Uma visão geral do OpenHands, o agente open source de codificação com IA: arquitetura, setup local com Ollama, correção prática de bug, segurança e limitações, e comparação com Claude Code, Cursor e GitHub Copilot.
OpenHands é uma plataforma open source para desenvolvimento de software com IA, construída em torno de um agente que inspeciona seu repositório, edita arquivos, executa comandos e roda testes. É parte da virada para o desenvolvimento agentic — você passa uma tarefa completa para o agente e ele vai executando passo a passo até concluir ou precisar do seu input.
Neste artigo, vou apresentar a arquitetura do OpenHands e seus principais recursos, mostrar como configurá-lo com um modelo local e compará-lo com Claude Code, Cursor e GitHub Copilot.
OpenHands é uma plataforma open source para criar e executar agentes de IA que trabalham com código.
O nome cobre duas coisas. A primeira é o projeto — um conjunto de repositórios com um SDK, um servidor, uma interface web e um serviço hospedado. A segunda é o agente de codificação que roda por cima de tudo isso.
Veja como funciona:
Software Agent SDK: um conjunto de APIs em Python e REST para criar agentes que trabalham com código e o motor por trás do OpenHands CLI e do OpenHands Cloud
Agent Server: expõe execução do agente, conversas, ferramentas e workspaces via APIs REST e WebSocket
Agent Canvas: uma única interface no navegador para conversas, arquivos, saída do terminal, configuração de modelos, back-ends e automações
OpenHands Cloud: serviço gerenciado e comercial para times que não querem operar sua própria infraestrutura de backend e sandbox
Quando a maioria das pessoas diz "OpenHands", está se referindo ao agente. É essa a parte que vou usar neste artigo.
Normalmente, você passa uma tarefa de software para o agente, aponta um workspace com seu código e ele executa a tarefa com as ferramentas que tem. O conjunto padrão inclui um terminal, um editor de arquivos e um rastreador de tarefas.
O workspace não precisa ser o seu laptop. Os agentes podem usar a máquina local como workspace ou rodar em ambientes efêmeros, como em Docker ou Kubernetes.
OpenHands também não te prende a um provedor de modelo. Você pode usá-lo com Claude, GPT ou qualquer outro LLM, incluindo modelos locais. O Agent Canvas inclusive roda agentes de terceiros como Claude Code e Codex no lugar do agente padrão do OpenHands.
Em resumo, OpenHands é uma plataforma de agentes aberta que você roda nos seus próprios termos.
Como o OpenHands funciona
OpenHands roda em um loop.
Um assistente de chat recebe seu prompt e retorna texto. O agente do OpenHands recebe uma tarefa, executa uma ação, olha o resultado e decide o próximo passo.
O loop do agente OpenHands
A ideia geral é esta:
Receber a tarefa: você descreve o objetivo em linguagem natural, por exemplo: "Corrija o relatório mensal para não juntar meses de anos diferentes"
Inspecionar o repositório: o agente lista diretórios, abre arquivos e busca por código relacionado à tarefa
Definir um plano: ele divide a tarefa em etapas e registra no seu rastreador de tarefas
Editar ou criar arquivos: modifica o código com seu editor de arquivos
Executar comandos e testes: roda a suíte de testes ou o app no terminal
Inspecionar resultados: lê a saída, incluindo erros e asserções que falharam
Iterar: se algo ainda estiver quebrado, volta, ajusta o plano e tenta novamente
O loop para quando a tarefa termina ou quando o agente precisa de algo que só você pode fornecer, como uma credencial ausente ou uma decisão de requisitos.
A etapa 6 diferencia o OpenHands da concorrência. Uma ferramenta de autocompletar não vê o que acontece quando o código roda. O OpenHands vê e, por isso, consegue reagir a um teste que falhou e corrigir a causa.
Principais recursos do OpenHands
Autocomplete apenas sugere texto; o OpenHands age no seu projeto. Veja como.
Edição de código
OpenHands edita arquivos diretamente e não fica limitado a um único arquivo por vez.
Digamos que uma função precise de um novo nome. O agente atualiza a definição, encontra todos os pontos de chamada e ajusta os testes que a referenciam — tudo dentro de uma única tarefa.
Terminal e uso de ferramentas
O agente tem seu próprio terminal. Ele pode instalar dependências, rodar scripts, executar testes e ler a saída de qualquer comando.
Você também pode conectar servidores MCP (Model Context Protocol) para dar ao agente ferramentas com as quais ele não foi originalmente projetado para trabalhar, como um rastreador de issues ou um cliente de banco de dados.
Entendimento do repositório
A maioria dos geradores de código só vê o que você cola no prompt.
OpenHands abre o repositório e o explora. Ele consegue ler o README, seguir imports e olhar os testes existentes para entender a estrutura do projeto. Isso aumenta a chance de suas alterações se encaixarem no código que já existe.
Tarefas longas criam outro problema — o histórico de conversa cresce além do que o modelo comporta. O OpenHands lida com isso com um condensador de contexto, que resume partes mais antigas da conversa para o agente continuar trabalhando.
Escolha de modelo
As chamadas de modelo passam pelo LiteLLM, então você pode usar qualquer provedor e modelo que ele suporte. A documentação do OpenHands recomenda modelos das famílias Claude, GPT e Gemini, além de modelos open-weight bem avaliados no OpenHands Index.
Se seu código não pode sair da sua máquina, você pode rodar um modelo local. OpenHands conecta-se a servidores locais como LM Studio, Ollama, vLLM e SGLang.
Um ponto importante: o modelo muda muito os resultados. Alguns modelos locais têm dificuldade em usar ferramentas de forma confiável, mesmo com janela de contexto ampla.
Execução autônoma de tarefas
Depois que você entrega a tarefa, o agente roda o loop por conta própria. Você não precisa colar erros no chat nem dizer qual arquivo abrir em seguida.
O Agent Canvas leva isso além com automações. Elas integram com Slack, GitHub, Linear e outras ferramentas, e rodam em agendamento ou em resposta a webhooks.
Mas autonomia não garante correção. Você ainda precisa revisar o diff e os resultados dos testes antes de fazer merge.
Como usar o OpenHands
A melhor forma de entender o OpenHands é dar a ele um bug e ver o que acontece.
Nesta seção, vou rodar o OpenHands localmente no Docker, conectá-lo a um modelo local via Ollama e pedir para corrigir um bug em um pequeno projeto em Python.
Configurar o OpenHands
Você pode rodar o OpenHands de algumas maneiras:
Lançador via CLI: instale com uv tool install openhands --python 3.14 e inicie a interface gráfica com openhands serve
Docker: rode o contêiner do app diretamente com um único comando docker run
Agent Canvas: o novo cliente no navegador que conecta a back-ends locais, self-hosted, Cloud ou Enterprise
OpenHands Cloud: a versão hospedada, se você preferir não rodar nada por conta própria
Vou usar a opção Docker com a GUI Local. A documentação do OpenHands agora lista essa aplicação web baseada em Docker como descontinuada e aponta o Agent Canvas como substituto, mas ela ainda está documentada e é a forma mais rápida de colocar uma GUI no ar.
Você vai precisar do Docker Desktop no macOS, Linux ou Windows com WSL. No macOS, abra o Docker Desktop, vá em Settings > Advanced e habilite o socket padrão do Docker.
OpenHands usa o mount do socket do Docker para iniciar um contêiner sandbox separado, e o agente executa seus comandos dentro desse sandbox, não no seu host.
Quando os logs mostrarem que o servidor subiu, abra http://localhost:3000 no navegador.
Página de boas-vindas do OpenHands
Conectar um modelo
OpenHands não faz nada até você fornecer um modelo.
Estou usando o Devstral Small 2, o modelo de 24B da Mistral voltado para codificação agentic. Ele é leve o suficiente para rodar em uma única RTX 4090 ou em um Mac com 32 GB de RAM. Requer o Ollama 0.13.3 ou superior.
Inicie o Ollama com uma janela de contexto maior e faça o pull do modelo:
Não ignore o tamanho do contexto. O padrão do Ollama é 4096 tokens, pequeno demais até para comportar o system prompt do OpenHands. A documentação pede pelo menos 22000.
No OpenHands, abra Settings, vá até a aba LLM e ative Advanced. Depois, defina:
Custom Model:openai/devstral-small-2:latest
Base URL:http://host.docker.internal:11434/v1
API Key: qualquer valor de placeholder, como local-llm
Configurações de LLM para um modelo local via Ollama
O prefixo openai/ diz ao OpenHands para falar com o Ollama por sua API compatível com OpenAI. A chave de API não é usada, mas o campo não pode ficar vazio.
Abrir um repositório
Por padrão, o OpenHands não vê seus arquivos. Você precisa montar o projeto no sandbox.
Para este exemplo, crie uma pasta chamada budget-tracker/project com dois arquivos. O primeiro soma gastos por mês:
# budget.pydefmonthly_totals(transactions):"""Sum spending per month, keyed as 'YYYY-MM'.
Each transaction is a (date, amount) tuple, for example ("2025-01-15", 42.0).
"""
totals ={}for date, amount in transactions:
month = date[5:7]
totals[month]= totals.get(month,0)+ amount
return totalsTecnologia
A docstring promete chaves no formato YYYY-MM, mas date[5:7] pega só o mês. Janeiro de 2025 e janeiro de 2026 vão parar no mesmo bucket.
O segundo arquivo traz dois testes que evidenciam o bug:
O formato é host_path:container_path:mode. Seu projeto aparece no sandbox em /workspace, e rwpermite que o agente edite.
Monte apenas o projeto que você quer que o agente altere. Qualquer coisa montada como leitura e escrita em /workspace pode ser modificada pelo agente.
Dar uma tarefa ao agente
Comece uma nova conversa e descreva o problema como se fosse um relatório de bug:
Os totais mensais juntam gastos do mesmo mês em anos diferentes.
Encontre a causa, corrija e rode os testes para confirmar que passam.
Só isso. Você não precisa apontar o agente para budget.py nem dizer qual linha está errada.
Saída da conversa
A partir daqui, o loop do agente assume. Ele vasculha /workspace, lê os dois arquivos e roda os testes para ver o que falha. Depois, edita o código e roda os testes novamente.
O agente rodando pytest no terminal do sandbox
Revisar as alterações
O agente diz que terminou. Agora você pode ver as diferenças abrindo o editor de código e inspecionando as mudanças.
Você também pode rodar git diff para ver as diferenças.
Veja o que conferir:
O código-fonte: a correção deve estar em budget.py
Os testes: garanta que o agente não editou test_budget.py só para as asserções passarem
A execução dos testes: rode python -m pytest você mesmo — não confie apenas no resumo do agente
Arquitetura do OpenHands
OpenHands tem seis partes principais, e cada uma tem um papel específico.
Como os componentes do OpenHands se conectam
Modelo de IA
O modelo faz o raciocínio. Ele recebe a tarefa e o histórico da conversa e responde com uma mensagem ou uma chamada de ferramenta.
O modelo não altera seus arquivos nem executa nada. Ele apenas decide o que deve acontecer a seguir. As chamadas passam pelo LiteLLM, então o mesmo agente funciona com um provedor hospedado ou um modelo local como o Devstral usado no artigo.
Lógica do agente
O agente fica entre o modelo e todo o restante. Ele roda o loop raciocínio-ação, ou seja, pede ao modelo a próxima ação, executa a ferramenta e trata o resultado ou o erro.
Ele também decide o que o modelo pode ver. O agente gerencia o histórico com condensadores e adiciona skills e prompts a cada consulta ao modelo.
Cada passo é registrado. O agente executa ações e recebe observações, e a conversa mantém esse histórico de eventos. O modelo vê esses eventos no turno seguinte, então sabe o que já aconteceu.
Ferramentas e ações
Ferramentas são como o agente afeta qualquer coisa fora do modelo. O conjunto padrão inclui terminal, editor de arquivos e rastreador de tarefas, e você pode adicionar mais via servidores MCP.
O modelo solicita uma ação, como "rodar pytest" ou "substituir a linha 8 em budget.py". A ferramenta executa e retorna uma observação, como a saída do teste ou o arquivo atualizado.
Antes de rodar, a ação passa por uma verificação de segurança. O analisador de segurança avalia cada ação e pode pausar o agente para sua aprovação.
Ambiente de desenvolvimento
As ferramentas não rodam na sua máquina. Elas rodam dentro de um sandbox.
No setup com Docker, o OpenHands executa o agent server em seu próprio contêiner. Por isso o artigo monta o socket do Docker — o contêiner do app precisa dele para iniciar o sandbox.
O sandbox não precisa ser local. Agentes também rodam em workspaces efêmeros, como em Docker ou Kubernetes, e o Agent Server expõe execução, ferramentas e workspaces via APIs REST e WebSocket. A lógica do agente fica igual, não importa onde o sandbox roda.
Repositório
O repositório é onde o agente trabalha. Ele entra no sandbox de duas formas: uma pasta local que você monta, como no artigo, ou um repo conectado pelas integrações com GitHub, GitLab ou Bitbucket.
Um repositório também pode dizer ao agente como se comportar. Um arquivo AGENTS.md na raiz é injetado no system prompt no início da conversa. Instruções mais focadas ficam em .agents/skills/, onde o agente vê primeiro um resumo e só carrega o conteúdo completo quando precisa.
Aqui é onde você coloca regras do projeto que o agente não tem como adivinhar, como "rode os testes com make test, não com pytest".
Revisão humana
Você é a última parte da arquitetura.
OpenHands suporta três políticas de confirmação: aprovar toda ação, aprovar nada ou aprovar apenas ações arriscadas. A última depende do analisador de segurança, que rotula cada ação como risco LOW, MEDIUM, HIGH ou UNKNOWN. NeverConfirm é o padrão, então o agente roda sem parar a menos que você mude isso.
O segundo checkpoint vem no final. O trabalho do agente só termina quando você lê o diff e confere os resultados dos testes.
Workflows no OpenHands
Mostrei como corrigir um bug de uma linha, mas claro que o OpenHands lida com tarefas muito maiores.
O que essas tarefas têm em comum é que exigem mais de um passo. Aqui vão seis tipos de trabalho onde o loop do agente faz sentido.
Correção de bugs
O bug mostrado aqui era fácil de ver em um único arquivo. No mundo real, quase nunca é assim.
Suponha que os logs da aplicação mostrem um KeyError em produção e a stack trace aponte para uma função a três chamadas de onde os dados ruins entram. Você cola a stack trace no OpenHands e pede uma correção.
O agente segue a cadeia de chamadas até a origem dos dados, escreve um teste que reproduz o erro e confirma que o teste falha. Depois, corrige o código e roda a suíte inteira de testes para checar se nada mais quebrou.
Procure por um teste de reprodução. Ele prova que o agente encontrou o bug de verdade, e não apenas o ponto onde o erro aparece.
Implementação de features
Trabalhos de feature geralmente alteram mais arquivos do que você imagina.
Digamos que um script de relatório de linha de comando precise de uma flag --since para filtrar transações por data. O agente precisa encontrar o parser de argumentos, adicionar a flag, passar o valor para a lógica de filtro e atualizar o texto de ajuda. Depois, escreve testes para o novo comportamento e atualiza o README.
Isso dá quatro ou cinco arquivos para uma pequena feature. O agente controla tudo no seu rastreador de tarefas, então não para depois que o primeiro item funciona.
Refatoração de código
Refatorar é mudar a estrutura sem mudar o comportamento, e a suíte de testes prova que o comportamento não mudou.
Imagine um projeto com um grande arquivo utils.py misturando helpers de data, string e arquivo. Você pede ao OpenHands para dividir em três módulos.
O agente cria os novos módulos, move as funções e atualiza cada import no codebase. Ele roda os testes após cada movimento. Assim, se algo quebrar, sabe qual mudança causou.
Escrita de testes
Código sem teste é um ponto de partida comum para agentes, porque a tarefa é clara e fácil de verificar.
Digamos que um módulo de parsing de datas não tenha testes. O agente lê as funções, escreve casos em pytest para entradas normais e edge cases como strings vazias, anos bissextos e formatos inválidos, e os executa.
Se um novo teste falha, o agente precisa decidir se o teste está errado ou se o código tem um bug. Essa decisão você deve conferir pessoalmente.
Investigação de codebases existentes
Nem toda tarefa exige mudar código.
Você pode perguntar ao OpenHands coisas como "Onde este app valida a entrada do usuário antes de chegar ao banco de dados?" O agente pesquisa o codebase, segue chamadas entre arquivos e responde com caminhos de arquivo e referências de linha.
Isso é prático quando você entra em um novo projeto ou retoma um código que não mexe há meses. Para trabalho somente leitura, monte o repositório com modo :ro no lugar de :rw, para o agente não conseguir alterar nada, nem por engano.
Execução e depuração de aplicações
Alguns bugs só aparecem com a aplicação rodando.
Suponha que um endpoint de API retorne erro 500 e os testes não o cubram. O agente inicia o servidor no terminal, envia uma requisição com curl e lê a traceback nos logs do servidor.
Depois, corrige o código, reinicia o servidor e envia a mesma requisição. Se a resposta ainda estiver errada, o loop continua daí.
É o mesmo ciclo editar-rodar-checar que você faria, só que o agente cuida de cada restart e cada tentativa.
OpenHands vs. outros agentes de codificação com IA
OpenHands não é a única ferramenta que recebe uma tarefa e trabalha nela de forma autônoma. Claude Code, Cursor e GitHub Copilot já têm recursos de agente, mas com diferenças importantes.
OpenHands vs Claude Code
Estes dois são os mais parecidos. Ambos rodam um loop de agente que lê código, edita arquivos, executa comandos e checa resultados.
A primeira diferença é a propriedade. Cada repositório público do OpenHands tem sua própria licença open source, e você pode ler, modificar e fazer self-host de tudo. Claude Code é a ferramenta proprietária de codificação agentic da Anthropic, disponível no terminal, IDE, app desktop e navegador.
Isso leva à questão do modelo. Claude Code é construído em torno dos modelos Claude da Anthropic. OpenHands funciona com qualquer provedor suportado pelo LiteLLM, incluindo o setup local com Ollama do artigo.
O fluxo de trabalho do dia a dia também difere. Claude Code começou como uma ferramenta de terminal, e muita gente ainda usa assim. OpenHands depende da interface no navegador; seu CLI é completo, mas mantido principalmente por estabilidade.
Ambas as ferramentas permitem controlar o comportamento do agente. Claude Code lê CLAUDE.md, configurações, hooks, skills, comandos e subagentes do diretório .claude. OpenHands lê AGENTS.md e skills do repositório, e o SDK permite você construir seus próprios agentes em Python.
A autonomia também funciona diferente. Claude Code controla o uso de ferramentas com modos de permissão, hooks e regras de allow/deny, e pode isolar comandos. OpenHands executa todo comando dentro de um sandbox Docker por padrão e adiciona políticas de confirmação por cima.
Em resumo, Claude Code é a opção polida que você instala e usa na hora, enquanto o OpenHands pede mais configuração e te dá mais controle em troca. E eles não são excludentes. O Agent Canvas pode rodar o Claude Code como agente no lugar do agente padrão do OpenHands.
OpenHands vs Cursor
Cursor é um editor de código com IA. OpenHands é uma plataforma de agentes. Essa é a principal diferença, e as demais derivam dela.
No Cursor, você trabalha no editor e o agente atua ao seu lado. Você vê as edições surgirem nos arquivos, aceita ou rejeita e continua digitando. No OpenHands, você descreve uma tarefa, o agente trabalha em um sandbox e você revisa o resultado. A GUI inclui uma visão do VS Code dentro do sandbox, mas não é onde a maior parte do trabalho acontece.
O acesso ao repositório segue a mesma divisão. O agente do Cursor trabalha no código aberto no seu editor. O OpenHands trabalha no que você monta no sandbox ou conecta via integração com Git.
A distância diminui com os Cloud Agents do Cursor. Eles rodam sem supervisão na nuvem e retornam o trabalho por branches e pull requests; exigem conta no GitHub, GitLab, Azure DevOps ou Bitbucket conectada e um plano pago. É próximo do que o OpenHands faz, mas na infraestrutura do Cursor.
Extensibilidade é onde mais diferem. Cursor suporta servidores MCP e regras de projeto, mas o editor e o agente são produtos fechados. Com OpenHands, você pode alterar o próprio agente, hospedar onde quiser e rodar em modelo local.
OpenHands vs GitHub Copilot
GitHub Copilot começou como uma ferramenta de autocompletar no editor e a partir daí ganhou recursos de agente. OpenHands já nasceu como agente.
A maior força do Copilot é onde ele vive. Funciona dentro do VS Code e das IDEs JetBrains, e seu agente em nuvem atua diretamente no GitHub. OpenHands não tem esse nível de integração com IDE.
Para tarefas no nível do repositório, o agente em nuvem do Copilot é a comparação mais próxima. Você atribui uma issue e ele trabalha em um ambiente de desenvolvimento efêmero alimentado por GitHub Actions, onde pode rodar testes e linters antes de enviar. OpenHands Cloud faz algo similar quando você menciona @openhands em uma issue ou comentário de pull request.
A principal diferença é a plataforma. O agente em nuvem do Copilot está disponível para todos os planos pagos do Copilot em repositórios no GitHub. OpenHands funciona com GitHub, GitLab, Bitbucket ou uma pasta local e pode rodar no seu próprio hardware, se você quiser.
Copilot permite escolher um modelo por tarefa, mas apenas entre os modelos oferecidos pelo GitHub. OpenHands não tem essa restrição.
Aqui vai um resumo rápido:
OpenHands
Claude Code
Cursor
GitHub Copilot
Fonte
Open source
Proprietário
Proprietário
Proprietário
Modelos
Qualquer provedor LiteLLM, incluindo local
Modelos Claude
Múltiplos provedores + modelos próprios
Modelos oferecidos pelo GitHub
Interface principal
Interface no navegador, SDK
Terminal, IDE, desktop, navegador
Editor de código com IA
Extensão de IDE, GitHub
Onde o agente roda
Sandbox Docker, local ou remoto
Sua máquina ou a nuvem da Anthropic
Seu editor ou a nuvem do Cursor
Sua IDE ou GitHub Actions
Self-hosting
Sim
Não
Apenas Enterprise
Não
OpenHands comparado com outros agentes de IA
OpenHands para times de engenharia de software
Para um desenvolvedor individual, OpenHands é uma ferramenta que você abre quando precisa. Para um time, não é assim.
A maioria dos times já organiza o trabalho em torno de issues, e o OpenHands Cloud se integra a isso. Ele integra com GitHub, GitLab e Bitbucket, além de Slack, Jira e Linear. Você pode mencionar @openhands em uma issue ou comentário de pull request, e o agente assume a tarefa a partir dali.
E tem o trabalho que ninguém pede, mas todo mundo precisa. As automações do Agent Canvas rodam por agenda ou em resposta a webhooks. Por exemplo, um time pode compartilhar um Agent Server para revisão de código e atualização de dependências, enquanto cada dev roda agentes pessoais no próprio laptop.
Os testes funcionam como no artigo. O agente roda a suíte no sandbox antes de reportar. Mas a execução no sandbox não substitui o CI — seu pipeline continua rodando em todo pull request, igual ao código escrito por humanos.
Pull requests são outro ponto. Quando o OpenHands Cloud trabalha com GitHub, ele solicita tokens de curta duração que expiram em oito horas, com acesso de leitura e escrita a conteúdos, issues, pull requests e workflows. Em instalações Enterprise self-hosted, o agente usa a autorização GitHub do usuário que o acionou, então toda mudança fica traçada a uma pessoa.
É assim que a responsabilidade deve funcionar. O agente pode abrir o pull request, mas um desenvolvedor aprova. Proteções de branch e revisões obrigatórias valem para PRs do agente como valem para todos os outros.
Ambientes isolados fazem tudo isso funcionar em escala. Cada tarefa roda no seu próprio sandbox, então dois agentes corrigindo dois bugs não sobrescrevem arquivos um do outro nem disputam a mesma porta.
Segurança e sandboxing no OpenHands
Uma ferramenta de autocompletar sempre sugere texto — cabe a você aceitar.
Um agente é diferente. Ele percorre seu projeto, executa comandos, instala pacotes e edita arquivos por conta própria, muitas vezes sem perguntar. A pergunta deixa de ser "esse código está correto?" para "o que o agente rodou para chegar aqui?"
Ambientes de execução isolados
O sandbox em Docker protege seus arquivos e programas do host, seus recursos e outros contêineres e processos. Se o agente rodar um comando destrutivo, o dano fica limitado ao contêiner.
Há uma exceção no setup local. O contêiner do app monta o socket do Docker do host para iniciar sandboxes, e acesso a esse socket significa controle do Docker na sua máquina.
Permissões do repositório
O sandbox só protege o que você não montar. Arquivos e diretórios montados podem ser modificados ou apagados.
Monte apenas o projeto em que você está trabalhando — nunca seu diretório home. Para tarefas de leitura, use o modo :ro. Em integrações com Git, dê acesso apenas aos repositórios necessários e nada além.
Segredos e credenciais
Se você fornecer credenciais, como chaves de API ou tokens, o agente pode usá-las. E um agente que consegue ler um segredo também pode imprimi-lo em logs ou enviá-lo para algum lugar.
Então não monte pastas com arquivos .env contendo chaves de produção. Dê ao agente credenciais de teste com escopo limitado e gire-as com frequência.
Acesso à rede
Por padrão, o agente acessa a internet de dentro do contêiner. Ele precisa disso para instalar pacotes, mas também pode alcançar qualquer serviço externo.
Isso abre espaço para prompt injection. Uma página web ou um comentário em issue pode incluir instruções que o agente pode seguir. O GitHub limita esse risco no seu agente em nuvem com um firewall que restringe o acesso por padrão, e vale considerar limites semelhantes no seu setup OpenHands.
Execução de comandos
Você pode controlar quais comandos rodam sem aprovação. OpenHands suporta três políticas de confirmação: aprovar tudo, aprovar nada ou aprovar apenas ações arriscadas. NeverConfirm é o padrão.
A opção "ações arriscadas" tem um ponto de atenção. O analisador de segurança padrão usa o nível de risco que o próprio modelo atribui às suas ações. Um modelo pode rotular um comando destrutivo como LOW e ele vai rodar sem pedir. O analisador classifica risco para a camada de política — ele não bloqueia nada sozinho, e a documentação recomenda combiná-lo com o isolamento do Docker.
Revisão das alterações geradas
Tudo acima limita o que o agente pode fazer. Mas a fase de revisão é essencial porque é como você verifica o que ele fez.
Leia o diff completo, não só os arquivos que você esperava mudar. Dê atenção extra à configuração de CI, arquivos de dependência e scripts. No OpenHands Cloud, o token do GitHub do agente inclui escrita em workflows, então uma mudança em .github/workflows pode alterar o que roda no seu pipeline.
Limitações do OpenHands
O código que o OpenHands escreve ainda pode ter bugs. Testes passando só indicam que o código bate com os testes — e o agente pode escrever ambos. Se os testes forem fracos, o código pode passar e ainda assim estar errado.
Tarefas complexas geralmente precisam de você no loop. Requisitos vagos ou uma decisão de design que o agente não pode tomar vão pará-lo ou, pior, desviá-lo da direção certa.
Com um modelo hospedado forte, o OpenHands lida bem com tarefas multi-arquivo. Com um modelo local pequeno, você verá falhas em chamadas de ferramentas e respostas de chatbot; e mesmo com janela de contexto grande, alguns modelos locais não usam ferramentas de forma confiável.
Loops de agente também custam mais do que chat. Cada passo envia o histórico de conversa de volta ao modelo, e tarefas longas levam muitos passos. A documentação do OpenHands alerta que o agente emite muitos prompts ao LLM e recomenda limites de gasto e monitoramento de uso. O condensador de contexto ajuda, mas resume etapas antigas, então detalhes podem se perder em tarefas longas.
O acesso a ferramentas adiciona risco de segurança. Um agente com terminal e rede pode causar dano real se seguir instruções ruins — por isso o sandbox e a sua revisão são tão importantes.
E toda alteração ainda precisa de uma pessoa para aprovar. Tenha isso sempre em mente.
OpenHands e o futuro dos agentes de codificação em IA
As ferramentas de codificação com IA evoluíram de autocompletar para chat e agora para agentes que executam tarefas inteiras. OpenHands é um dos projetos que estão puxando esse último passo.
A direção está clara no setor. O Cursor descreve uma nova era em que agentes autônomos na nuvem assumem tarefas maiores por mais tempo. O Copilot agora pega issues do GitHub e do Linear. O Claude Code roda no terminal, no navegador e no Slack.
Plataformas open source têm um papel específico nessa mudança. Com OpenHands, você pode inspecionar como o agente funciona, rodá-lo na sua própria infraestrutura e escolher o modelo. Para times com regras rígidas de dados, muitas vezes é a única forma permitida de usar agentes.
Tarefas mais longas trazem novos problemas. Um agente que trabalha por uma hora toma mais decisões do que um que trabalha por um minuto, e cada decisão é uma chance de se afastar do que você queria. Modelos melhores ajudam, mas sandboxes, políticas de confirmação e revisão também.
Conclusão
O que diferencia o OpenHands dos concorrentes é o controle. Você pode ler o código-fonte, hospedar no seu próprio hardware e rodar com qualquer modelo, inclusive local. Ferramentas comerciais mais fechadas, como Claude Code, Cursor e GitHub Copilot, oferecem uma experiência mais lapidada — mas nos termos deles.
Mas um agente com acesso ao seu terminal e aos seus repositórios ainda precisa de alguém para conferir seu trabalho. Lembre-se sempre de ler o diff e rodar os testes por conta própria.
Cientista de dados sênior baseado na Croácia. Principal redator técnico com mais de 700 artigos publicados, gerando mais de 10 milhões de visualizações. Autor do livro Automação do aprendizado de máquina com TPOT.
FAQs
O que é o OpenHands?⌄
OpenHands é uma plataforma open source para criar e executar agentes de IA que trabalham com código. Seu agente de codificação pode inspecionar um repositório, editar arquivos, rodar comandos e testes, e iterar nos resultados até concluir a tarefa. Você pode rodá-lo localmente no Docker, via SDK ou no OpenHands Cloud.
O OpenHands é gratuito para usar?⌄
O software OpenHands é open source, então você pode fazer self-host sem pagar licença. O que você paga é o modelo — provedores hospedados como Anthropic ou OpenAI cobram por token, e loops de agente usam muitos. Se você rodar um modelo local via Ollama ou LM Studio, o único custo é seu hardware. O OpenHands Cloud é um serviço comercial à parte.
Em que o OpenHands é diferente do GitHub Copilot ou do Cursor?⌄
Copilot e Cursor são centrados no editor, onde a IA trabalha ao seu lado enquanto você codifica. OpenHands é agent-first — você descreve a tarefa, o agente trabalha em um sandbox e você revisa o resultado. Ele também é open source, funciona com qualquer modelo suportado pelo LiteLLM e roda na sua própria infraestrutura, algo que nem Copilot nem Cursor oferecem no mesmo nível.
Posso rodar o OpenHands com um modelo local?⌄
Sim. OpenHands conecta-se a servidores locais como LM Studio, Ollama, vLLM e SGLang por APIs compatíveis com OpenAI. Escolha um modelo voltado para codificação agentic, como Devstral Small 2 ou Qwen3.6-35B-A3B, e defina a janela de contexto para pelo menos 22000 tokens. Modelos menores e genéricos costumam falhar em chamadas de ferramentas e responder como um chatbot.
É seguro dar acesso do OpenHands ao meu código?⌄
OpenHands executa os comandos do agente dentro de um sandbox Docker, o que protege seu sistema host da maioria dos erros. Mas tudo que você montar no sandbox pode ser modificado ou apagado, e qualquer credencial fornecida pode ser usada pelo agente. Por padrão, o agente não pede aprovação antes de agir, então monte apenas o projeto necessário, use credenciais de teste com escopo limitado e revise todo diff antes do merge.
Dá uma olhada nos melhores assistentes de codificação de IA, incluindo ferramentas de código aberto, gratuitas e comerciais para melhorar sua experiência de desenvolvimento.
Saiba como OpenAI e Anthropic lideram o desenvolvimento de IA com abordagens únicas. Explore produtos como o ChatGPT e os modelos inovadores que elas oferecem.
Descubra o Sora da OpenAI: uma IA inovadora de texto para vídeo que revolucionará a IA multimodal em 2024. Explore seus recursos, inovações e impacto potencial.
GPT-4 alternativas de código aberto que podem oferecer desempenho semelhante e exigem menos recursos computacionais para serem executadas. Esses projetos vêm com instruções, fontes de código, pesos de modelos, conjuntos de dados e interface de usuário do chatbot.
Saiba mais sobre os principais tipos de agentes de IA, como eles interagem com os ambientes e como são usados em todos os setores. Entenda o reflexo simples, baseado em modelo, baseado em meta, baseado em utilidade, agentes de aprendizagem e muito mais.
Uma visão geral abrangente da API Assistants com nosso artigo, que oferece uma análise aprofundada de seus recursos, usos no setor, orientação de configuração e práticas recomendadas para maximizar seu potencial em vários aplicativos de negócios.
OpenHands é uma plataforma open source para desenvolvimento de software com IA, construída em torno de um agente que inspeciona seu repositório, edita arquivos, executa comandos e roda testes. É parte da virada para o desenvolvimento agentic — você passa uma tarefa completa para o agente e ele vai executando passo a passo até concluir ou precisar do seu input.
Neste artigo, vou apresentar a arquitetura do OpenHands e seus principais recursos, mostrar como configurá-lo com um modelo local e compará-lo com Claude Code, Cursor e GitHub Copilot.
O que são agentes de IA? Inscreva-se na nossa trilha de aprendizado AI Agent Fundamentals para descobrir como agentes de IA podem transformar a sua forma de trabalhar.
O que é o OpenHands?
OpenHands é uma plataforma open source para criar e executar agentes de IA que trabalham com código.
O nome cobre duas coisas. A primeira é o projeto — um conjunto de repositórios com um SDK, um servidor, uma interface web e um serviço hospedado. A segunda é o agente de codificação que roda por cima de tudo isso.
Veja como funciona:
Quando a maioria das pessoas diz "OpenHands", está se referindo ao agente. É essa a parte que vou usar neste artigo.
Normalmente, você passa uma tarefa de software para o agente, aponta um workspace com seu código e ele executa a tarefa com as ferramentas que tem. O conjunto padrão inclui um terminal, um editor de arquivos e um rastreador de tarefas.
O workspace não precisa ser o seu laptop. Os agentes podem usar a máquina local como workspace ou rodar em ambientes efêmeros, como em Docker ou Kubernetes.
OpenHands também não te prende a um provedor de modelo. Você pode usá-lo com Claude, GPT ou qualquer outro LLM, incluindo modelos locais. O Agent Canvas inclusive roda agentes de terceiros como Claude Code e Codex no lugar do agente padrão do OpenHands.
Em resumo, OpenHands é uma plataforma de agentes aberta que você roda nos seus próprios termos.
Como o OpenHands funciona
OpenHands roda em um loop.
Um assistente de chat recebe seu prompt e retorna texto. O agente do OpenHands recebe uma tarefa, executa uma ação, olha o resultado e decide o próximo passo.
O loop do agente OpenHands
A ideia geral é esta:
O loop para quando a tarefa termina ou quando o agente precisa de algo que só você pode fornecer, como uma credencial ausente ou uma decisão de requisitos.
A etapa 6 diferencia o OpenHands da concorrência. Uma ferramenta de autocompletar não vê o que acontece quando o código roda. O OpenHands vê e, por isso, consegue reagir a um teste que falhou e corrigir a causa.
Principais recursos do OpenHands
Autocomplete apenas sugere texto; o OpenHands age no seu projeto. Veja como.
Edição de código
OpenHands edita arquivos diretamente e não fica limitado a um único arquivo por vez.
Digamos que uma função precise de um novo nome. O agente atualiza a definição, encontra todos os pontos de chamada e ajusta os testes que a referenciam — tudo dentro de uma única tarefa.
Terminal e uso de ferramentas
O agente tem seu próprio terminal. Ele pode instalar dependências, rodar scripts, executar testes e ler a saída de qualquer comando.
Você também pode conectar servidores MCP (Model Context Protocol) para dar ao agente ferramentas com as quais ele não foi originalmente projetado para trabalhar, como um rastreador de issues ou um cliente de banco de dados.
Entendimento do repositório
A maioria dos geradores de código só vê o que você cola no prompt.
OpenHands abre o repositório e o explora. Ele consegue ler o README, seguir imports e olhar os testes existentes para entender a estrutura do projeto. Isso aumenta a chance de suas alterações se encaixarem no código que já existe.
Tarefas longas criam outro problema — o histórico de conversa cresce além do que o modelo comporta. O OpenHands lida com isso com um condensador de contexto, que resume partes mais antigas da conversa para o agente continuar trabalhando.
Escolha de modelo
As chamadas de modelo passam pelo LiteLLM, então você pode usar qualquer provedor e modelo que ele suporte. A documentação do OpenHands recomenda modelos das famílias Claude, GPT e Gemini, além de modelos open-weight bem avaliados no OpenHands Index.
Se seu código não pode sair da sua máquina, você pode rodar um modelo local. OpenHands conecta-se a servidores locais como LM Studio, Ollama, vLLM e SGLang.
Um ponto importante: o modelo muda muito os resultados. Alguns modelos locais têm dificuldade em usar ferramentas de forma confiável, mesmo com janela de contexto ampla.
Execução autônoma de tarefas
Depois que você entrega a tarefa, o agente roda o loop por conta própria. Você não precisa colar erros no chat nem dizer qual arquivo abrir em seguida.
O Agent Canvas leva isso além com automações. Elas integram com Slack, GitHub, Linear e outras ferramentas, e rodam em agendamento ou em resposta a webhooks.
Mas autonomia não garante correção. Você ainda precisa revisar o diff e os resultados dos testes antes de fazer merge.
Como usar o OpenHands
A melhor forma de entender o OpenHands é dar a ele um bug e ver o que acontece.
Nesta seção, vou rodar o OpenHands localmente no Docker, conectá-lo a um modelo local via Ollama e pedir para corrigir um bug em um pequeno projeto em Python.
Configurar o OpenHands
Você pode rodar o OpenHands de algumas maneiras:
Lançador via CLI: instale com
uv tool install openhands --python 3.14e inicie a interface gráfica comopenhands serveDocker: rode o contêiner do app diretamente com um único comando
docker runAgent Canvas: o novo cliente no navegador que conecta a back-ends locais, self-hosted, Cloud ou Enterprise
OpenHands Cloud: a versão hospedada, se você preferir não rodar nada por conta própria
Vou usar a opção Docker com a GUI Local. A documentação do OpenHands agora lista essa aplicação web baseada em Docker como descontinuada e aponta o Agent Canvas como substituto, mas ela ainda está documentada e é a forma mais rápida de colocar uma GUI no ar.
Você vai precisar do Docker Desktop no macOS, Linux ou Windows com WSL. No macOS, abra o Docker Desktop, vá em
Settings > Advancede habilite o socket padrão do Docker.Depois, inicie o app:
OpenHands usa o mount do socket do Docker para iniciar um contêiner sandbox separado, e o agente executa seus comandos dentro desse sandbox, não no seu host.
Quando os logs mostrarem que o servidor subiu, abra
http://localhost:3000no navegador.Página de boas-vindas do OpenHands
Conectar um modelo
OpenHands não faz nada até você fornecer um modelo.
Estou usando o Devstral Small 2, o modelo de 24B da Mistral voltado para codificação agentic. Ele é leve o suficiente para rodar em uma única RTX 4090 ou em um Mac com 32 GB de RAM. Requer o Ollama 0.13.3 ou superior.
Inicie o Ollama com uma janela de contexto maior e faça o pull do modelo:
Não ignore o tamanho do contexto. O padrão do Ollama é 4096 tokens, pequeno demais até para comportar o system prompt do OpenHands. A documentação pede pelo menos 22000.
No OpenHands, abra
Settings, vá até a abaLLMe ativeAdvanced. Depois, defina:Custom Model:
openai/devstral-small-2:latestBase URL:
http://host.docker.internal:11434/v1API Key: qualquer valor de placeholder, como
local-llmConfigurações de LLM para um modelo local via Ollama
O prefixo
openai/diz ao OpenHands para falar com o Ollama por sua API compatível com OpenAI. A chave de API não é usada, mas o campo não pode ficar vazio.Abrir um repositório
Por padrão, o OpenHands não vê seus arquivos. Você precisa montar o projeto no sandbox.
Para este exemplo, crie uma pasta chamada
budget-tracker/projectcom dois arquivos. O primeiro soma gastos por mês:A docstring promete chaves no formato
YYYY-MM, masdate[5:7]pega só o mês. Janeiro de 2025 e janeiro de 2026 vão parar no mesmo bucket.O segundo arquivo traz dois testes que evidenciam o bug:
Transforme a pasta em um repositório Git para ver depois o que o agente mudou:
Se você rodar
python -m pytestagora, os dois testes falham:Testes falhando
Para dar acesso ao OpenHands, pare o contêiner e adicione uma linha ao comando
docker run:Então o comando completo fica assim:
O formato é
host_path:container_path:mode. Seu projeto aparece no sandbox em/workspace, erwpermite que o agente edite.Monte apenas o projeto que você quer que o agente altere. Qualquer coisa montada como leitura e escrita em
/workspacepode ser modificada pelo agente.Dar uma tarefa ao agente
Comece uma nova conversa e descreva o problema como se fosse um relatório de bug:
Os totais mensais juntam gastos do mesmo mês em anos diferentes.
Encontre a causa, corrija e rode os testes para confirmar que passam.
Só isso. Você não precisa apontar o agente para
budget.pynem dizer qual linha está errada.Saída da conversa
A partir daqui, o loop do agente assume. Ele vasculha
/workspace, lê os dois arquivos e roda os testes para ver o que falha. Depois, edita o código e roda os testes novamente.O agente rodando pytest no terminal do sandbox
Revisar as alterações
O agente diz que terminou. Agora você pode ver as diferenças abrindo o editor de código e inspecionando as mudanças.
A correção certa é uma linha em
budget.py:budget.py corrigido
Você também pode rodar
git diffpara ver as diferenças.Veja o que conferir:
O código-fonte: a correção deve estar em
budget.pyOs testes: garanta que o agente não editou
test_budget.pysó para as asserções passaremA execução dos testes: rode
python -m pytestvocê mesmo — não confie apenas no resumo do agenteArquitetura do OpenHands
OpenHands tem seis partes principais, e cada uma tem um papel específico.
Como os componentes do OpenHands se conectam
Modelo de IA
O modelo faz o raciocínio. Ele recebe a tarefa e o histórico da conversa e responde com uma mensagem ou uma chamada de ferramenta.
O modelo não altera seus arquivos nem executa nada. Ele apenas decide o que deve acontecer a seguir. As chamadas passam pelo LiteLLM, então o mesmo agente funciona com um provedor hospedado ou um modelo local como o Devstral usado no artigo.
Lógica do agente
O agente fica entre o modelo e todo o restante. Ele roda o loop raciocínio-ação, ou seja, pede ao modelo a próxima ação, executa a ferramenta e trata o resultado ou o erro.
Ele também decide o que o modelo pode ver. O agente gerencia o histórico com condensadores e adiciona skills e prompts a cada consulta ao modelo.
Cada passo é registrado. O agente executa ações e recebe observações, e a conversa mantém esse histórico de eventos. O modelo vê esses eventos no turno seguinte, então sabe o que já aconteceu.
Ferramentas e ações
Ferramentas são como o agente afeta qualquer coisa fora do modelo. O conjunto padrão inclui terminal, editor de arquivos e rastreador de tarefas, e você pode adicionar mais via servidores MCP.
O modelo solicita uma ação, como "rodar
pytest" ou "substituir a linha 8 embudget.py". A ferramenta executa e retorna uma observação, como a saída do teste ou o arquivo atualizado.Antes de rodar, a ação passa por uma verificação de segurança. O analisador de segurança avalia cada ação e pode pausar o agente para sua aprovação.
Ambiente de desenvolvimento
As ferramentas não rodam na sua máquina. Elas rodam dentro de um sandbox.
No setup com Docker, o OpenHands executa o agent server em seu próprio contêiner. Por isso o artigo monta o socket do Docker — o contêiner do app precisa dele para iniciar o sandbox.
O sandbox não precisa ser local. Agentes também rodam em workspaces efêmeros, como em Docker ou Kubernetes, e o Agent Server expõe execução, ferramentas e workspaces via APIs REST e WebSocket. A lógica do agente fica igual, não importa onde o sandbox roda.
Repositório
O repositório é onde o agente trabalha. Ele entra no sandbox de duas formas: uma pasta local que você monta, como no artigo, ou um repo conectado pelas integrações com GitHub, GitLab ou Bitbucket.
Um repositório também pode dizer ao agente como se comportar. Um arquivo
AGENTS.mdna raiz é injetado no system prompt no início da conversa. Instruções mais focadas ficam em.agents/skills/, onde o agente vê primeiro um resumo e só carrega o conteúdo completo quando precisa.Aqui é onde você coloca regras do projeto que o agente não tem como adivinhar, como "rode os testes com
make test, não compytest".Revisão humana
Você é a última parte da arquitetura.
OpenHands suporta três políticas de confirmação: aprovar toda ação, aprovar nada ou aprovar apenas ações arriscadas. A última depende do analisador de segurança, que rotula cada ação como risco LOW, MEDIUM, HIGH ou UNKNOWN. NeverConfirm é o padrão, então o agente roda sem parar a menos que você mude isso.
O segundo checkpoint vem no final. O trabalho do agente só termina quando você lê o diff e confere os resultados dos testes.
Workflows no OpenHands
Mostrei como corrigir um bug de uma linha, mas claro que o OpenHands lida com tarefas muito maiores.
O que essas tarefas têm em comum é que exigem mais de um passo. Aqui vão seis tipos de trabalho onde o loop do agente faz sentido.
Correção de bugs
O bug mostrado aqui era fácil de ver em um único arquivo. No mundo real, quase nunca é assim.
Suponha que os logs da aplicação mostrem um
KeyErrorem produção e a stack trace aponte para uma função a três chamadas de onde os dados ruins entram. Você cola a stack trace no OpenHands e pede uma correção.O agente segue a cadeia de chamadas até a origem dos dados, escreve um teste que reproduz o erro e confirma que o teste falha. Depois, corrige o código e roda a suíte inteira de testes para checar se nada mais quebrou.
Procure por um teste de reprodução. Ele prova que o agente encontrou o bug de verdade, e não apenas o ponto onde o erro aparece.
Implementação de features
Trabalhos de feature geralmente alteram mais arquivos do que você imagina.
Digamos que um script de relatório de linha de comando precise de uma flag
--sincepara filtrar transações por data. O agente precisa encontrar o parser de argumentos, adicionar a flag, passar o valor para a lógica de filtro e atualizar o texto de ajuda. Depois, escreve testes para o novo comportamento e atualiza o README.Isso dá quatro ou cinco arquivos para uma pequena feature. O agente controla tudo no seu rastreador de tarefas, então não para depois que o primeiro item funciona.
Refatoração de código
Refatorar é mudar a estrutura sem mudar o comportamento, e a suíte de testes prova que o comportamento não mudou.
Imagine um projeto com um grande arquivo
utils.pymisturando helpers de data, string e arquivo. Você pede ao OpenHands para dividir em três módulos.O agente cria os novos módulos, move as funções e atualiza cada import no codebase. Ele roda os testes após cada movimento. Assim, se algo quebrar, sabe qual mudança causou.
Escrita de testes
Código sem teste é um ponto de partida comum para agentes, porque a tarefa é clara e fácil de verificar.
Digamos que um módulo de parsing de datas não tenha testes. O agente lê as funções, escreve casos em pytest para entradas normais e edge cases como strings vazias, anos bissextos e formatos inválidos, e os executa.
Se um novo teste falha, o agente precisa decidir se o teste está errado ou se o código tem um bug. Essa decisão você deve conferir pessoalmente.
Investigação de codebases existentes
Nem toda tarefa exige mudar código.
Você pode perguntar ao OpenHands coisas como "Onde este app valida a entrada do usuário antes de chegar ao banco de dados?" O agente pesquisa o codebase, segue chamadas entre arquivos e responde com caminhos de arquivo e referências de linha.
Isso é prático quando você entra em um novo projeto ou retoma um código que não mexe há meses. Para trabalho somente leitura, monte o repositório com modo
:rono lugar de:rw, para o agente não conseguir alterar nada, nem por engano.Execução e depuração de aplicações
Alguns bugs só aparecem com a aplicação rodando.
Suponha que um endpoint de API retorne erro 500 e os testes não o cubram. O agente inicia o servidor no terminal, envia uma requisição com
curle lê a traceback nos logs do servidor.Depois, corrige o código, reinicia o servidor e envia a mesma requisição. Se a resposta ainda estiver errada, o loop continua daí.
É o mesmo ciclo editar-rodar-checar que você faria, só que o agente cuida de cada restart e cada tentativa.
OpenHands vs. outros agentes de codificação com IA
OpenHands não é a única ferramenta que recebe uma tarefa e trabalha nela de forma autônoma. Claude Code, Cursor e GitHub Copilot já têm recursos de agente, mas com diferenças importantes.
OpenHands vs Claude Code
Estes dois são os mais parecidos. Ambos rodam um loop de agente que lê código, edita arquivos, executa comandos e checa resultados.
A primeira diferença é a propriedade. Cada repositório público do OpenHands tem sua própria licença open source, e você pode ler, modificar e fazer self-host de tudo. Claude Code é a ferramenta proprietária de codificação agentic da Anthropic, disponível no terminal, IDE, app desktop e navegador.
Isso leva à questão do modelo. Claude Code é construído em torno dos modelos Claude da Anthropic. OpenHands funciona com qualquer provedor suportado pelo LiteLLM, incluindo o setup local com Ollama do artigo.
O fluxo de trabalho do dia a dia também difere. Claude Code começou como uma ferramenta de terminal, e muita gente ainda usa assim. OpenHands depende da interface no navegador; seu CLI é completo, mas mantido principalmente por estabilidade.
Ambas as ferramentas permitem controlar o comportamento do agente. Claude Code lê
CLAUDE.md, configurações, hooks, skills, comandos e subagentes do diretório.claude. OpenHands lêAGENTS.mde skills do repositório, e o SDK permite você construir seus próprios agentes em Python.A autonomia também funciona diferente. Claude Code controla o uso de ferramentas com modos de permissão, hooks e regras de allow/deny, e pode isolar comandos. OpenHands executa todo comando dentro de um sandbox Docker por padrão e adiciona políticas de confirmação por cima.
Em resumo, Claude Code é a opção polida que você instala e usa na hora, enquanto o OpenHands pede mais configuração e te dá mais controle em troca. E eles não são excludentes. O Agent Canvas pode rodar o Claude Code como agente no lugar do agente padrão do OpenHands.
OpenHands vs Cursor
Cursor é um editor de código com IA. OpenHands é uma plataforma de agentes. Essa é a principal diferença, e as demais derivam dela.
No Cursor, você trabalha no editor e o agente atua ao seu lado. Você vê as edições surgirem nos arquivos, aceita ou rejeita e continua digitando. No OpenHands, você descreve uma tarefa, o agente trabalha em um sandbox e você revisa o resultado. A GUI inclui uma visão do VS Code dentro do sandbox, mas não é onde a maior parte do trabalho acontece.
O acesso ao repositório segue a mesma divisão. O agente do Cursor trabalha no código aberto no seu editor. O OpenHands trabalha no que você monta no sandbox ou conecta via integração com Git.
A distância diminui com os Cloud Agents do Cursor. Eles rodam sem supervisão na nuvem e retornam o trabalho por branches e pull requests; exigem conta no GitHub, GitLab, Azure DevOps ou Bitbucket conectada e um plano pago. É próximo do que o OpenHands faz, mas na infraestrutura do Cursor.
Extensibilidade é onde mais diferem. Cursor suporta servidores MCP e regras de projeto, mas o editor e o agente são produtos fechados. Com OpenHands, você pode alterar o próprio agente, hospedar onde quiser e rodar em modelo local.
OpenHands vs GitHub Copilot
GitHub Copilot começou como uma ferramenta de autocompletar no editor e a partir daí ganhou recursos de agente. OpenHands já nasceu como agente.
A maior força do Copilot é onde ele vive. Funciona dentro do VS Code e das IDEs JetBrains, e seu agente em nuvem atua diretamente no GitHub. OpenHands não tem esse nível de integração com IDE.
Para tarefas no nível do repositório, o agente em nuvem do Copilot é a comparação mais próxima. Você atribui uma issue e ele trabalha em um ambiente de desenvolvimento efêmero alimentado por GitHub Actions, onde pode rodar testes e linters antes de enviar. OpenHands Cloud faz algo similar quando você menciona
@openhandsem uma issue ou comentário de pull request.A principal diferença é a plataforma. O agente em nuvem do Copilot está disponível para todos os planos pagos do Copilot em repositórios no GitHub. OpenHands funciona com GitHub, GitLab, Bitbucket ou uma pasta local e pode rodar no seu próprio hardware, se você quiser.
Copilot permite escolher um modelo por tarefa, mas apenas entre os modelos oferecidos pelo GitHub. OpenHands não tem essa restrição.
Aqui vai um resumo rápido:
OpenHands comparado com outros agentes de IA
OpenHands para times de engenharia de software
Para um desenvolvedor individual, OpenHands é uma ferramenta que você abre quando precisa. Para um time, não é assim.
A maioria dos times já organiza o trabalho em torno de issues, e o OpenHands Cloud se integra a isso. Ele integra com GitHub, GitLab e Bitbucket, além de Slack, Jira e Linear. Você pode mencionar
@openhandsem uma issue ou comentário de pull request, e o agente assume a tarefa a partir dali.E tem o trabalho que ninguém pede, mas todo mundo precisa. As automações do Agent Canvas rodam por agenda ou em resposta a webhooks. Por exemplo, um time pode compartilhar um Agent Server para revisão de código e atualização de dependências, enquanto cada dev roda agentes pessoais no próprio laptop.
Os testes funcionam como no artigo. O agente roda a suíte no sandbox antes de reportar. Mas a execução no sandbox não substitui o CI — seu pipeline continua rodando em todo pull request, igual ao código escrito por humanos.
Pull requests são outro ponto. Quando o OpenHands Cloud trabalha com GitHub, ele solicita tokens de curta duração que expiram em oito horas, com acesso de leitura e escrita a conteúdos, issues, pull requests e workflows. Em instalações Enterprise self-hosted, o agente usa a autorização GitHub do usuário que o acionou, então toda mudança fica traçada a uma pessoa.
É assim que a responsabilidade deve funcionar. O agente pode abrir o pull request, mas um desenvolvedor aprova. Proteções de branch e revisões obrigatórias valem para PRs do agente como valem para todos os outros.
Ambientes isolados fazem tudo isso funcionar em escala. Cada tarefa roda no seu próprio sandbox, então dois agentes corrigindo dois bugs não sobrescrevem arquivos um do outro nem disputam a mesma porta.
Segurança e sandboxing no OpenHands
Uma ferramenta de autocompletar sempre sugere texto — cabe a você aceitar.
Um agente é diferente. Ele percorre seu projeto, executa comandos, instala pacotes e edita arquivos por conta própria, muitas vezes sem perguntar. A pergunta deixa de ser "esse código está correto?" para "o que o agente rodou para chegar aqui?"
Ambientes de execução isolados
O sandbox em Docker protege seus arquivos e programas do host, seus recursos e outros contêineres e processos. Se o agente rodar um comando destrutivo, o dano fica limitado ao contêiner.
Há uma exceção no setup local. O contêiner do app monta o socket do Docker do host para iniciar sandboxes, e acesso a esse socket significa controle do Docker na sua máquina.
Permissões do repositório
O sandbox só protege o que você não montar. Arquivos e diretórios montados podem ser modificados ou apagados.
Monte apenas o projeto em que você está trabalhando — nunca seu diretório home. Para tarefas de leitura, use o modo
:ro. Em integrações com Git, dê acesso apenas aos repositórios necessários e nada além.Segredos e credenciais
Se você fornecer credenciais, como chaves de API ou tokens, o agente pode usá-las. E um agente que consegue ler um segredo também pode imprimi-lo em logs ou enviá-lo para algum lugar.
Então não monte pastas com arquivos
.envcontendo chaves de produção. Dê ao agente credenciais de teste com escopo limitado e gire-as com frequência.Acesso à rede
Por padrão, o agente acessa a internet de dentro do contêiner. Ele precisa disso para instalar pacotes, mas também pode alcançar qualquer serviço externo.
Isso abre espaço para prompt injection. Uma página web ou um comentário em issue pode incluir instruções que o agente pode seguir. O GitHub limita esse risco no seu agente em nuvem com um firewall que restringe o acesso por padrão, e vale considerar limites semelhantes no seu setup OpenHands.
Execução de comandos
Você pode controlar quais comandos rodam sem aprovação. OpenHands suporta três políticas de confirmação: aprovar tudo, aprovar nada ou aprovar apenas ações arriscadas. NeverConfirm é o padrão.
A opção "ações arriscadas" tem um ponto de atenção. O analisador de segurança padrão usa o nível de risco que o próprio modelo atribui às suas ações. Um modelo pode rotular um comando destrutivo como LOW e ele vai rodar sem pedir. O analisador classifica risco para a camada de política — ele não bloqueia nada sozinho, e a documentação recomenda combiná-lo com o isolamento do Docker.
Revisão das alterações geradas
Tudo acima limita o que o agente pode fazer. Mas a fase de revisão é essencial porque é como você verifica o que ele fez.
Leia o diff completo, não só os arquivos que você esperava mudar. Dê atenção extra à configuração de CI, arquivos de dependência e scripts. No OpenHands Cloud, o token do GitHub do agente inclui escrita em workflows, então uma mudança em
.github/workflowspode alterar o que roda no seu pipeline.Limitações do OpenHands
O código que o OpenHands escreve ainda pode ter bugs. Testes passando só indicam que o código bate com os testes — e o agente pode escrever ambos. Se os testes forem fracos, o código pode passar e ainda assim estar errado.
Tarefas complexas geralmente precisam de você no loop. Requisitos vagos ou uma decisão de design que o agente não pode tomar vão pará-lo ou, pior, desviá-lo da direção certa.
Com um modelo hospedado forte, o OpenHands lida bem com tarefas multi-arquivo. Com um modelo local pequeno, você verá falhas em chamadas de ferramentas e respostas de chatbot; e mesmo com janela de contexto grande, alguns modelos locais não usam ferramentas de forma confiável.
Loops de agente também custam mais do que chat. Cada passo envia o histórico de conversa de volta ao modelo, e tarefas longas levam muitos passos. A documentação do OpenHands alerta que o agente emite muitos prompts ao LLM e recomenda limites de gasto e monitoramento de uso. O condensador de contexto ajuda, mas resume etapas antigas, então detalhes podem se perder em tarefas longas.
O acesso a ferramentas adiciona risco de segurança. Um agente com terminal e rede pode causar dano real se seguir instruções ruins — por isso o sandbox e a sua revisão são tão importantes.
E toda alteração ainda precisa de uma pessoa para aprovar. Tenha isso sempre em mente.
OpenHands e o futuro dos agentes de codificação em IA
As ferramentas de codificação com IA evoluíram de autocompletar para chat e agora para agentes que executam tarefas inteiras. OpenHands é um dos projetos que estão puxando esse último passo.
A direção está clara no setor. O Cursor descreve uma nova era em que agentes autônomos na nuvem assumem tarefas maiores por mais tempo. O Copilot agora pega issues do GitHub e do Linear. O Claude Code roda no terminal, no navegador e no Slack.
Plataformas open source têm um papel específico nessa mudança. Com OpenHands, você pode inspecionar como o agente funciona, rodá-lo na sua própria infraestrutura e escolher o modelo. Para times com regras rígidas de dados, muitas vezes é a única forma permitida de usar agentes.
Tarefas mais longas trazem novos problemas. Um agente que trabalha por uma hora toma mais decisões do que um que trabalha por um minuto, e cada decisão é uma chance de se afastar do que você queria. Modelos melhores ajudam, mas sandboxes, políticas de confirmação e revisão também.
Conclusão
O que diferencia o OpenHands dos concorrentes é o controle. Você pode ler o código-fonte, hospedar no seu próprio hardware e rodar com qualquer modelo, inclusive local. Ferramentas comerciais mais fechadas, como Claude Code, Cursor e GitHub Copilot, oferecem uma experiência mais lapidada — mas nos termos deles.
Mas um agente com acesso ao seu terminal e aos seus repositórios ainda precisa de alguém para conferir seu trabalho. Lembre-se sempre de ler o diff e rodar os testes por conta própria.
Se você quer aprender a criar seu próprio agente do zero, assista ao nosso webinar Introduction to Creating AI Agents in Python.