Início Rápido do OpenHands Coding Assistant: Instalação, Opções de CLI e Exemplos

OpenHands é uma plataforma de código aberto e agnóstica em relação ao modelo para agentes de desenvolvimento de software impulsionados por IA. Ele permite que um agente se comporte mais como um parceiro de programação do que como uma simples ferramenta de autocompletar.

Ele pode trabalhar com arquivos, executar comandos em um ambiente sandbox e usar navegação na web quando necessário.

Este QuickStart concentra-se no OpenHands CLI, porque é a maneira mais rápida de ser produtivo diretamente do terminal, e mapeia-se limpaamente para padrões de automação como scripts e execuções de CI. Para uma visão mais ampla do espaço, veja o Ferramentas de Desenvolvedor de IA: O Guia Completo para Desenvolvimento Impulsionado por IA.

O que é OpenHands e o que ele faz de diferente

Um assistente de codificação de IA normalmente ajuda você a gerar ou editar código usando um modelo de linguagem. OpenHands estende essa ideia para um fluxo de trabalho “agente”: o sistema pode planejar iterativamente, tomar ações (como escrever arquivos ou executar testes), observar resultados e continuar até que a tarefa esteja completa.

OpenHands também é amplamente conhecido como o projeto anteriormente chamado de OpenDevin, e evoluiu para uma plataforma impulsionada pela comunidade com várias maneiras de usá-lo: um CLI, uma GUI web local, uma UI hospedada na nuvem e um SDK.

De uma perspectiva de engenharia, o diferencial chave é que OpenHands é construído em torno de um ambiente de execução (um sandbox) para que um agente possa executar comandos e ferramentas com segurança, em vez de apenas produzir texto. O artigo do OpenHands descreve um ambiente de tempo de execução sandboxizado com Docker, com shell e capacidade de navegação, especificamente para suportar padrões de interação realistas semelhantes aos de desenvolvedores.

Instalar o OpenHands CLI

OpenHands suporta múltiplos métodos de instalação. Para a maioria dos desenvolvedores, é melhor começar com uma instalação local do CLI (iteração rápida) e, opcionalmente, adicionar fluxos de trabalho baseados em Docker posteriormente, quando você quiser isolamento estrito em torno da execução.

Instalar com uv

A documentação atual do OpenHands CLI recomenda a instalação com uv e exige Python 3.12+.

uv tool install openhands --python 3.12
openhands

A atualização é igualmente direta.

uv tool upgrade openhands --python 3.12

Por que uv importa na prática: uv fornece melhor isolamento do seu ambiente de projeto atual e é necessário para servidores MCP padrão.

Instalar o binário CLI standalone

Se você quiser um fluxo de instalação de “comando único”, o OpenHands fornece um script de instalação.

curl -fsSL https://install.openhands.dev/install.sh | sh
openhands

No macOS, você pode precisar permitir explicitamente o binário em Privacidade & Segurança antes que ele seja executado.

Executar via Docker para isolamento

Se você preferir manter a instalação contida, a documentação do CLI também mostra um fluxo baseado em Docker. Esta abordagem depende de montar um diretório que você quer que o OpenHands acesse e passar seu ID de usuário para evitar a criação de arquivos pertencentes ao root no workspace montado.

export SANDBOX_VOLUMES="$PWD:/workspace"

docker run -it \
  --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.12.0-python \
  -e SANDBOX_USER_ID=$(id -u) \
  -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/root/.openhands \
  --add-host host.docker.internal:host-gateway \
  --name openhands-cli-$(date +%Y%m%d%H%M%S) \
  python:3.12-slim \
  bash -c "pip install uv && uv tool install openhands --python 3.12 && openhands"

Primeira execução: configuração e onde as configurações ficam

Na primeira execução, o CLI guia você na configuração das configurações de LLM necessárias e as armazena para sessões futuras. A documentação do CLI afirma que as configurações são salvas em ~/.openhands/settings.json e o histórico de conversas é armazenado em ~/.openhands/conversations, mas quando instalei o OpenHands recentemente, ele armazenou a configuração em ~/.openhands/agent_settings.json, então talvez a documentação não esteja totalmente correta.

Para configurações mais profundas e integração de ferramentas, o OpenHands também documenta arquivos de configuração adicionais, como ~/.openhands/agent_settings.json (configurações de agente e LLM), ~/.openhands/cli_config.json (preferências do CLI) e ~/.openhands/mcp.json (servidores MCP).

Configurando OpenHands com Ollama local e llama.cpp

OpenHands funciona com qualquer backend local compatível com OpenAI — Ollama, LocalAI, llama.cpp e outros. Se você não tiver certeza de qual usar, consulte Ollama vs vLLM vs LM Studio: Melhor Maneira de Executar LLMs Localmente para uma comparação.

Quando você inicia o OpenHands pela primeira vez, ele mostra a página de configurações. Quando você já passou por esta etapa inicial, pode abrir esta página novamente digitando /settings e depois ctrl+j. Agora digite:

• no campo Custom Model: ollama/devstral-small-2:24b, ou qual for seu modelo local favorito,
• e no campo Base Url: http://localhost:11434

Para uma referência rápida sobre comandos Ollama, veja a Lista de Comandos Ollama CLI: serve, run, ps e gerenciamento de modelos.

Para editar o arquivo de configuração do OpenHands manualmente, por exemplo, se você não gosta de como a página de configurações se parece, execute:

nano ~/.openhands/agent_settings.json

ou, se preferir um editor com mais GUI:

gedit GUI ~/.openhands/agent_settings.json

Existe uma propriedade llm em dois lugares, configurei-os para ter estas subpropriedades, entre outras, para apontar para o ollama:

"llm":{"model":"ollama/devstral-small-2:24b","api_key":"aaa","base_url":"http://localhost:11434"

Para apontar o OpenHands para uma instância local do llama.cpp - o mesmo, em dois lugares:

"llm":{"model":"openai/devstral-small-2:24b","api_key":"aaa","base_url":"http://localhost:11434"

Para conectar ao llama.cpp, configurei:

• “model”:“openai/Qwen3.5-35B-A3B-UD-IQ3_S.gguf”
• “base_url”:“http://localhost:8080/v1”

e estava iniciando o llama.cpp com o comando (veja Quickstart do llama.cpp com CLI e Server para detalhes das flags):

./llama.cpp/llama-server \
    -m /mnt/ggufs/Qwen3.5-35B-A3B-UD-IQ3_S.gguf \
    --ctx-size 70000 \
    -ngl 40 \
    --temp 0.6 \
    --top-p 0.95 \
    --top-k 20 \
    --min-p 0.00

O OpenHands conseguiu conectar-se e completar minha solicitação de teste crie para mim uma ferramenta cli em Go, que chamaria os endpoints indexnow do bing e de outros motores de busca para notificar sobre mudanças no meu site com sucesso - com código-fonte, executável e README.md.

Como o OpenHands CLI funciona na prática

O comando padrão openhands inicia uma experiência interativa de terminal. OpenHands fornece uma paleta de comandos e comandos durante a sessão para que você possa guiar o agente rapidamente enquanto ele está trabalhando.

Controles interativos úteis para saber logo no início incluem abrir a paleta de comandos, pausar o agente e sair do aplicativo.

• Ctrl+P abre a paleta de comandos.
• Esc pausa o agente em execução.
• Ctrl+Q ou /exit sai do CLI.

Dentro do CLI, o OpenHands também suporta comandos com prefixo de barra, como /help, /new e /condense, o que é valioso se você quiser gerenciar conversas longas sem reiniciar.

OpenHands não para em uma interface de terminal. O CLI inclui múltiplas interfaces que mapeiam bem para diferentes fluxos de trabalho de desenvolvedores:

• Modo headless para automação e CI.
• Interface web para executar a experiência do CLI em um navegador.
• Servidor GUI para o aplicativo web local completo, lançado via Docker.
• Integração IDE via ACP para fluxos de trabalho baseados em editor.

Principais parâmetros de linha de comando que você realmente usará

Em alto nível, o OpenHands CLI segue este formato:

openhands [OPÇÕES] [COMANDO]

Isso inclui opções globais (coisas como tarefas, retomar, headless), além de subcomandos (serve, web, cloud, acp, mcp, login, logout).

Opções principais para o trabalho diário

As globais mais comumente usadas são:

• -t, --task para iniciar a conversa com uma tarefa inicial.
• -f, --file para iniciar a partir de um arquivo, o que é útil quando você quer tarefas comprometidas ao controle de versão.
• --resume [ID] e --last para continuar execuções anteriores.
• --headless para execução não interativa, tipicamente em automação.
• --json para transmitir saída JSONL no modo headless para parsing de máquina.

Segurança e aprovações também são de primeira classe:

• --always-approve aprova automaticamente ações sem solicitar confirmação.
• --llm-approve usa um analisador de segurança baseado em LLM para aprovação de ações.

Configuração de modelo e provedor via variáveis de ambiente

OpenHands suporta variáveis de ambiente para configuração de modelos:

• LLM_API_KEY define a chave de API do seu provedor.
• LLM_MODEL e LLM_BASE_URL podem ser aplicados como sobrescritas quando você executa openhands --override-with-envs.

Exemplo de fluxo de sobrescrita:

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="your-api-key"
openhands --override-with-envs

OpenHands nota explicitamente que as sobrescritas aplicadas com --override-with-envs não são persistidas.

Subcomandos que valem a pena conhecer

Você não precisa de todos os subcomandos no primeiro dia, mas estes são os que surgem rapidamente:

• openhands serve inicia o servidor GUI completo usando Docker, tipicamente acessível em http://localhost:3000, com opções como --mount-cwd e --gpu.
• openhands web inicia o CLI como um aplicativo web acessível pelo navegador, padrão na porta 12000.
• openhands login autentica com OpenHands Cloud e busca suas configurações.
• openhands cloud cria uma nova conversa no OpenHands Cloud a partir do CLI.

Exemplos de copiar e colar que você pode usar imediatamente

A maneira mais rápida de obter valor do OpenHands é tratá-lo como um agente de codificação orientado a tarefas. Mantenha as tarefas concisas, inclua nomes de arquivos e peça testes ou verificação quando apropriado.

Iniciar uma sessão de codificação interativa com uma tarefa inicial

Esta é a “experiência padrão do desenvolvedor” e um dos padrões mais comuns.

openhands -t "Corrigir o bug em auth.py e adicionar um teste de regressão"

A documentação do OpenHands CLI mostra exatamente essa ideia para inicializar uma sessão com -t.

Inicializar uma tarefa a partir de um arquivo

Usar um arquivo é útil quando você quer repetibilidade, revisão de equipe ou reutilização de CI.

cat > task.txt << 'EOF'
Refatorar o módulo de conexão com o banco de dados.
Adicionar testes unitários e garantir que a suíte de testes passe.
EOF

openhands -f task.txt

O Quick Start do CLI suporta explicitamente iniciar a partir de um arquivo de tarefa com -f.

Executar no modo headless para CI ou automação

O modo headless executa sem a interface interativa e é construído para pipelines de CI e scripts automatizados.

openhands --headless -t "Adicionar testes unitários para auth.py e executá-los"

Duas realidades de engenharia importantes aqui:

• O modo headless requer --task ou --file.
• O modo headless sempre executa no modo sempre-aprovado e não pode ser alterado, e --llm-approve não está disponível no modo headless. Trate-o como automação poderosa e execute-o em um ambiente controlado.

Para integrar com parsing de logs ou outras ferramentas, habilite a saída JSONL:

openhands --headless --json -t "Criar um aplicativo Flask simples com endpoint de healthcheck" > openhands-output.jsonl

OpenHands documenta --json como streaming de eventos JSONL no modo headless e mostra redirecionando a saída para um arquivo.

Retomar trabalho sem perder o contexto

Retomar é crítico uma vez que você começa a usar o OpenHands para mudanças não triviais.

Listar conversas recentes:

openhands --resume

Retomar a mais recente:

openhands --resume --last

Ou retomar um ID de conversa específico:

openhands --resume abc123def456

Estes fluxos são documentados na referência de comandos do CLI e no guia “Retomar Conversas”.

Executar o CLI em um navegador quando precisar

openhands web inicia um CLI acessível pela web (porta padrão 12000).

openhands web

Se você estiver executando localmente, vincular apenas ao localhost é um padrão sensato:

openhands web --host 127.0.0.1 --port 12000

OpenHands avisa que expor a interface web à rede requer medidas de segurança apropriadas, porque ela fornece acesso total às capacidades do OpenHands.

Segurança, solução de problemas e pontos críticos

A alavanca de segurança mais importante no OpenHands CLI são as aprovações:

• O CLI interativo pode solicitar confirmação antes de ações sensíveis, e você pode configurar configurações de confirmação durante a sessão.
• --always-approve remove o atrito, mas também remove salvaguardas.
• --llm-approve adiciona um analisador baseado em LLM para aprovações.
• O modo headless sempre aprova, então reserve para automação em ambientes controlados.

Ao trabalhar com código local, prefira padrões de acesso explícitos e de privilégio mínimo:

• Para o servidor GUI, openhands serve --mount-cwd monta seu diretório atual em /workspace para que o agente possa ler e modificar seus arquivos de projeto.
• Para execuções do CLI baseadas em Docker, use SANDBOX_VOLUMES para definir exatamente quais diretórios o OpenHands pode acessar.

Se você tiver diretórios de estado do OpenHands mais antigos, o OpenHands nota um caminho de migração de ~/.openhands-state para ~/.openhands na documentação de configuração local e orientações de solução de problemas.

Finalmente, se você estiver integrando o OpenHands em scripts, os códigos de saída são documentados como:

• 0 sucesso
• 1 erro ou tarefa falhou
• 2 argumentos inválidos

Minha experiência com OpenHands

Para mim, o OpenHands funcionou bem, mas não sempre… Tentei fazê-lo funcionar com Devstral-Small-2 hospedado no Ollama, e ele parava constantemente.

.

Embora o OpenHands tenha funcionado bem com Qwen 3.5 35b hospedado localmente no llama.cpp. Até agora, para mim, o OpenCode é muito mais confiável. Se você quiser levar o OpenCode ainda mais longe, o Oh My Opencode adiciona um sistema multi-agente completo por cima — agentes especialistas, execução paralela e decomposição automática de tarefas acionada por uma única palavra-chave ultrawork.