Pular para o conteúdo principal

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.
· 15 min leer

Explore com IA

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:

  • 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.

The OpenHands agent loop

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.

Depois, inicie o app:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8

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.

OpenHands welcome page

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:

OLLAMA_CONTEXT_LENGTH=32768 OLLAMA_HOST=0.0.0.0:11434 ollama serve &
ollama pull devstral-small-2:24b

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:

  1. Custom Model: openai/devstral-small-2:latest

  2. Base URL: http://host.docker.internal:11434/v1

  3. API Key: qualquer valor de placeholder, como local-llm

LLM settings for a local Ollama model

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.py
def monthly_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 totals

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:

# test_budget.py
from budget import monthly_totals


def test_same_month_in_different_years():
    transactions = [
        ("2025-01-10", 50.0),
        ("2025-01-20", 100.0),
        ("2026-01-12", 60.0),
    ]
    assert monthly_totals(transactions) == {"2025-01": 150.0, "2026-01": 60.0}


def test_single_month():
    transactions = [("2026-03-01", 20.0), ("2026-03-15", 5.5)]
    assert monthly_totals(transactions) == {"2026-03": 25.5}

Transforme a pasta em um repositório Git para ver depois o que o agente mudou:

cd budget-tracker
git init
git add .
git commit -m "Initial commit"

Se você rodar python -m pytest agora, os dois testes falham:

Failing tests

Testes falhando

Para dar acesso ao OpenHands, pare o contêiner e adicione uma linha ao comando docker run:

-e SANDBOX_VOLUMES=$HOME/budget-tracker:/workspace:rw \

Então o comando completo fica assim:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -e SANDBOX_VOLUMES=$HOME/Desktop/budget-tracker:/workspace:rw \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8

O formato é host_path:container_path:mode. Seu projeto aparece no sandbox em /workspace, e rw permite 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.

Conversation output

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.

The agent running pytest in the sandbox terminal

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:

month = date[:7]

Fixed budget.py

budget.py corrigido

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.

How the OpenHands components connect

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:

 OpenHandsClaude CodeCursorGitHub Copilot
FonteOpen sourceProprietárioProprietárioProprietário
ModelosQualquer provedor LiteLLM, incluindo localModelos ClaudeMúltiplos provedores + modelos própriosModelos oferecidos pelo GitHub
Interface principalInterface no navegador, SDKTerminal, IDE, desktop, navegadorEditor de código com IAExtensão de IDE, GitHub
Onde o agente rodaSandbox Docker, local ou remotoSua máquina ou a nuvem da AnthropicSeu editor ou a nuvem do CursorSua IDE ou GitHub Actions
Self-hostingSimNãoApenas EnterpriseNã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.

Se você quer aprender a criar seu próprio agente do zero, assista ao nosso webinar Introduction to Creating AI Agents in Python.

Dario Radečić

Autor

Dario Radečić

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.

Temas

Relacionado