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

Introdução rápida ao OpenHands CLI em minutos

Conteúdo da página

O 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 codificação do que como uma simples ferramenta de autocompletar.

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

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

openhands text user interface

O que é o OpenHands e o que ele faz de diferente

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

O OpenHands também é amplamente conhecido como o projeto anteriormente chamado OpenDevin, e cresceu para se tornar uma plataforma impulsionada pela comunidade com múltiplas formas de uso: um CLI, uma GUI web local, uma UI hospedada na nuvem e um SDK.

De uma perspectiva de engenharia, o principal diferenciador é que o 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 runtime com sandbox Docker com capacidade de shell e navegação, especificamente para suportar padrões de interação realistas semelhantes aos de desenvolvedores.

Instalar o CLI do OpenHands

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

Instalar com uv

A documentação atual do CLI do OpenHands recomenda instalar com uv e requer 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 o uv importa na prática: o uv oferece 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 e 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 o 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"

Configuração na primeira execução e onde as configurações ficam

Na primeira execução, o CLI guia você através da configuração de configurações 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 há pouco tempo, ele armazenou a configuração em ~/.openhands/agent_settings.json, então a documentação talvez 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 do agente e LLM), ~/.openhands/cli_config.json (preferências do CLI) e ~/.openhands/mcp.json (servidores MCP).

Configurando o OpenHands com Ollama local e llama.cpp

O OpenHands funciona com qualquer backend local compatível com OpenAI — Ollama, LocalAI, llama.cpp e outros. Se você não tem certeza qual usar, veja 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 outro modelo local favorito você tem,
  • e no campo Base Url: http://localhost:11434

openhands settings ollama mistral

Para uma referência rápida sobre comandos do Ollama, veja o Guia de atalhos do CLI Ollama: 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 parece, execute:

nano ~/.openhands/agent_settings.json

ou se você preferir um editor com mais interface gráfica:

gedit GUI ~/.openhands/agent_settings.json

Existe a propriedade llm em dois lugares, eu os configurei 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 e completar minha solicitação de teste crie para mim uma ferramenta de 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 CLI do OpenHands funciona na prática

O comando padrão openhands inicia uma experiência de terminal interativa. O OpenHands fornece uma paleta de comandos e comandos em sessão para que você possa dirigir o agente rapidamente enquanto ele estiver trabalhando.

Controles interativos úteis para saber cedo 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 prefixados com barra, como /help, /new e /condense, o que é valioso se você quiser gerenciar conversas longas sem reiniciar.

O OpenHands não para apenas em uma UI 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 de 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 CLI do OpenHands segue este formato:

openhands [OPTIONS] [COMMAND]

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 dia a dia

As opções 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 no 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 análise de máquina.

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

  • --always-approve aprova automaticamente ações sem solicitar.
  • --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

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

  • LLM_API_KEY define sua chave de API do provedor.
  • LLM_MODEL e LLM_BASE_URL podem ser aplicados como substituições quando você executa openhands --override-with-envs.

Exemplo de fluxo de substituição:

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="sua-chave-de-api"
openhands --override-with-envs

O OpenHands nota explicitamente que substituições 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 lança o servidor GUI completo usando Docker, tipicamente acessível em http://localhost:3000, com opções como --mount-cwd e --gpu.
  • openhands web lança o CLI como um aplicativo web acessível pelo navegador, com porta padrão 12000.
  • openhands login autentica com a OpenHands Cloud e busca suas configurações.
  • openhands cloud cria uma nova conversa na 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 CLI do OpenHands 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 roda sem a UI 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 importantes de engenharia aqui:

  • O modo headless requer --task ou --file.
  • O modo headless sempre executa no modo always-approve 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 análise 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

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

Retomar o 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 estã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

O OpenHands adverte que expor a interface web à rede requer medidas de segurança apropriadas, pois fornece acesso total às capacidades do OpenHands.

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

O alavanca de segurança mais importante no CLI do OpenHands 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 em 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-o 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 de 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 estão documentados como:

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

Minha experiência com o OpenHands

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

OpenHands com Ollama-hosted Devstral-Small-2.

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.