QuickStart do CLI do OpenHands: Instalação, Flags, Modo Headless

O OpenHands é um agente de codificação open-source que edita ficheiros e executa comandos num sandbox. Este guia rápido de CLI foi verificado em 26/10/2026 contra o pacote 1.16.0.

O pacote no PyPI é openhands 1.16.0, enviado a 8 de maio de 2026, com a dependência fixada em openhands-sdk==1.21.0. O README da tag requer Python 3.12 e uv 0.11.6 ou mais recente. O README da branch predefinida do OpenHands-CLI afirma que esse repositório não é mais mantido ativamente e encaminha novas instalações para o Agent Canvas. O modo headless e openhands acp continuam a fazer parte do conjunto de comandos da versão 1.16.0.

O guia de ferramentas de desenvolvimento com IA segue os outros agentes de terminal neste site. Esta página mantém-se focada na CLI do OpenHands: instalação, ficheiros de definições, URLs de modelos locais e as flags que um script efetivamente passa.

O que é a CLI

Um assistente de codificação com IA tipicamente gera ou edita código a partir de um prompt. O OpenHands estende isso para um loop de agente: planejar, tomar uma ação como escrever um ficheiro ou executar um teste, observar o resultado e continuar. O projeto era anteriormente chamado de OpenDevin. O paper do OpenHands descreve um runtime com sandbox Docker, incluindo shell e navegação, que é o modelo de execução que a CLI ainda envolve.

A libertação 1.16.0 documenta cinco formas de executar esse loop.

Agent Canvas, a instalação que o projeto documenta atualmente

A 3 de junho de 2026, as FAQs do OpenHands colocaram a UI de terminal em manutenção até 1 de outubro de 2026, e declararam que o modo headless e ACP permaneceriam totalmente suportados. A GUI local (openhands serve) ficaria em manutenção até o Agent Canvas poder executar sandboxes isolados e efémeros. Essa FAQ define manutenção como atualizações de dependências, correções de bugs críticos e novos LLMs. O repositório principal do OpenHands lançou o Agent Canvas 1.33.0 a 23 de outubro de 2026.

agent-canvas inicia a UI atual e o seu backend. openhands serve inicia a GUI legada e não inicia o Agent Canvas.

O Agent Canvas requer Node.js 24 ou posterior e uv. Uma primeira execução sem instalação global:

npx @openhands/agent-canvas

O processo escuta em http://localhost:8000. Fechar esse terminal para o backend local. Uma instalação global é npm install -g @openhands/agent-canvas, depois agent-canvas. O caminho npm executa o servidor do agente como o seu utilizador, pelo que o agente pode atuar sobre ficheiros locais com as permissões da sua conta.

O caminho Docker publica a porta apenas no localhost e monta um diretório de projetos:

mkdir -p ~/projects

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -v openhands-data:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

O contentor serve a UI em http://localhost:8000/canvas. O volume nomeado openhands-data mantém as definições após --rm. No Linux, ligar por bind ~/.openhands para esta imagem falha com unable to open database file: o utilizador do contentor é UID 10001, e um diretório anfitrião é normalmente proprietário do seu próprio UID. A página de instalação usa o volume nomeado por essa razão. As definições já em ~/.openhands não são copiadas para um novo volume.

Instalar a CLI do OpenHands

Use a CLI quando ainda quiser openhands --headless ou openhands acp. O wheel publicado instala apenas no Python 3.12 (==3.12.* no PyPI). O uv deve ser 0.11.6 ou mais recente. No Windows, a página de instalação diz para executar os comandos no WSL (Ubuntu).

Instalar com uv

uv tool install openhands --python 3.12
openhands

Atualize com a mesma pinagem de interpretador:

uv tool upgrade openhands --python 3.12

A página de configuração local diz que o uv é o que isola a CLI do virtualenv do projeto, e que os servidores MCP predefinidos o requerem.

Instalar o binário standalone

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

No macOS, um diálogo do Gatekeeper pode bloquear o binário (“openhands não pode ser aberto porque a Apple não consegue verificá-lo para software malicioso”). O caminho da página de instalação é Definições do Sistema, Privacidade e Segurança, depois Permitir De Qualquer Modo sob Segurança, depois executar openhands novamente.

Executar a CLI via Docker

O contentor da página de instalação define AGENT_SERVER_IMAGE_TAG para a imagem do agent-server. O uv tool install openhands dentro do contentor é a CLI do PyPI. A tag nesse exemplo, verificada para esta página, é 1.26.0-python. Cópias mais antigas deste comando usavam 1.12.0-python.

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.26.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"

SANDBOX_USER_ID=$(id -u) faz com que o utilizador do sandbox corresponda ao utilizador anfitrião, para que o agente não deixe ficheiros pertencentes ao root no workspace montado. SANDBOX_VOLUMES é o diretório ao qual o agente pode aceder.

OPENHANDS_VERSION seleciona a versão da imagem Docker para openhands serve. Não altera a versão da CLI do PyPI.

Ficheiros de definições

Na primeira lançamento, a CLI pede as definições do modelo e escreve-as sob ~/.openhands/. O README da 1.16.0 e a referência de comandos nomeiam estes ficheiros:

A página de instalação ainda diz aos utilizadores Docker para prepararem ~/.openhands/settings.json. O README da CLI e o AgentStore na árvore 1.16.0 persistem a especificação do agente em agent_settings.json. Uma instalação da CLI que pulou o nome do ficheiro da página de instalação e escreveu agent_settings.json corresponde a essa fonte.

create_and_save_from_settings constrói dois objetos LLM a partir do mesmo modelo, chave de API e URL base: um para o agente e um para o condensador de resumo. É por isso que um ficheiro guardado repete os campos llm. Edite o ficheiro do agente com qualquer editor:

nano ~/.openhands/agent_settings.json

LLM_API_KEY, LLM_MODEL e LLM_BASE_URL são ignorados a menos que opte por usar a sobreposição. A sobreposição não é guardada:

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

OPENHANDS_CLOUD_URL define o servidor cloud predefinido. Os comandos cloud e login têm por predefinição https://app.all-hands.dev quando essa variável não está definida.

Atualizações a partir de uma CLI mais antiga que a 1.0.0 necessitam das definições introduzidas novamente. A página de instalação diz que o formato de configuração mudou na 1.0.0.

Modelos locais

O guia de LLMs locais datado de 21 de maio de 2026 recomenda o Qwen3.6-35B-A3B como o primeiro modelo local a tentar. Exige uma GPU com pelo menos 24GB de VRAM para uma build quantizada, ou um Mac com Apple Silicon com pelo menos 64GB de memória unificada. A mesma página diz para definir o comprimento de contexto para pelo menos 22000 tokens, e que o predefinido de 4096 do Ollama é demasiado pequeno para o prompt de sistema.

Quando o agente nunca chama ferramentas, o guia trata isso como um limite do modelo e nomeia relatórios da comunidade para qwen2.5-coder-14b-instruct e qwopus3.5-27b-v3. O comparativo de alojamento local é a tabela servidor a servidor quando Ollama, vLLM, LM Studio ou LocalAI ainda é uma opção aberta.

Ollama

O arranque do Ollama do guia define o comprimento de contexto antes de ollama serve. A folha de dicas CLI do Ollama cobre serve, run e ps ao lado dessa variável.

OLLAMA_CONTEXT_LENGTH=32768 OLLAMA_HOST=0.0.0.0:11434 OLLAMA_KEEP_ALIVE=-1 ollama serve
ollama pull qwen3.6:35b-a3b

Para o OpenHands a correr em Docker, as definições do guia são modelo personalizado openai/qwen3.6:35b-a3b, URL base http://host.docker.internal:11434/v1 e qualquer chave de API placeholder. Uma CLI a correr no mesmo host que o Ollama usa http://127.0.0.1:11434/v1 em vez de host.docker.internal. O LM Studio Linux e outros servidores apenas de loopback são inacessíveis de um contentor em 127.0.0.1; a verificação do guia é ativar o serviço na rede local e fazer curl para host.docker.internal de dentro do contentor.

A página de terminal abre esse ecrã com Ctrl+P, depois Definições. Um perfil de CLI guardado usou um id de modelo ollama/ e uma URL base sem /v1:

• Modelo personalizado: ollama/devstral-small-2:24b
• URL base: http://localhost:11434

Essa sessão do Devstral-Small-2 é a que parou repetidamente. Os campos escritos para ela, tanto no LLM do agente como no LLM do condensador, foram:

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

llama.cpp e vLLM

O llama.cpp usou o prefixo compatível com OpenAI e uma URL base /v1, novamente nos dois objetos LLM:

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

O comando do servidor, com flags cobertas no guia rápido do llama.cpp, foi:

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

Contra esse servidor, a CLI terminou um cliente Go IndexNow: fonte, um executável e um README. O texto da tarefa foi create for me a cli tool in Go, that would call bing and other search engines' indexnow endpoints to notify about changes on my website.

O exemplo do vLLM do guia de LLMs locais para o modelo Qwen3.6 mais novo é um serve de duas GPUs. O guia rápido do vLLM passa pelas flags vllm serve e verificações de memória insuficiente. A string de modelo correspondente do OpenHands no guia é openai/Qwen3.6-35B-A3B, com URL base http://host.docker.internal:8000/v1 e a mesma --api-key com que o servidor foi iniciado (mykey no seu exemplo).

vllm serve Qwen/Qwen3.6-35B-A3B \
    --host 0.0.0.0 --port 8000 \
    --api-key mykey \
    --tensor-parallel-size 2 \
    --served-model-name Qwen3.6-35B-A3B \
    --enable-prefix-caching

Controles interativos

openhands sem subcomando abre a UI de terminal. A página de terminal lista estes controles:

Comandos de barra a partir da referência de comandos: /help, /new, /history, /confirm, /condense, /skills, /feedback, /exit. Alterações de modelo a partir da entrada Definições da paleta aplicam-se sem reinício. --exit-without-confirmation salta o diálogo de saída. --exp seleciona a UI textual e está documentado como uma flag de compatibilidade, já que essa UI já é a predefinida.

Flags e subcomandos

openhands [OPÇÕES] [COMANDO]

Opções globais na referência de comandos, verificadas contra argparsers/util.py na tag 1.16.0 para as flags de aprovação e ambiente:

--always-approve e --llm-approve não podem ser combinados. O modo interativo predefinido pergunta antes das ações.

Subcomandos que surgem quando a TUI não é suficiente:

• openhands serve inicia a GUI legada em Docker. --mount-cwd monta o diretório atual em /workspace. --gpu ativa o nvidia-docker.
• openhands web serve a CLI num navegador. --host tem por predefinição 0.0.0.0, --port 12000, --debug está desligado.
• openhands acp fala Agent Client Protocol em stdio. Flags: --resume, --last, --always-approve, --llm-approve, --streaming.
• openhands cloud -t "tarefa" abre uma conversa em cloud. --server-url sobrepõe https://app.all-hands.dev.
• openhands login e openhands logout gerem essa conta em cloud. logout sem --server-url faz logout de todos os servidores guardados.
• openhands mcp gere servidores: add, list, get, remove, enable, disable. add requer --transport de http, sse ou stdio.

Um servidor MCP do README 1.16.0:

openhands mcp list
openhands mcp add tavily --transport stdio \
  npx -- -y mcp-remote "https://mcp.tavily.com/mcp/?tavilyApiKey=<sua-chave-de-api>"
openhands mcp enable tavily
openhands mcp disable tavily

Exemplos

Tarefa interativa

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

Ficheiro de tarefa

cat > task.txt << 'EOF'
Refatorar o módulo de ligação à base de dados.
Adicionar testes unitários e garantir que a suite de testes passa.
EOF

openhands -f task.txt

Headless, incluindo JSONL

O modo headless requer --task ou --file. Executa sempre como always-approve, e --llm-approve é rejeitado lá. Trate o diretório de trabalho como um que o agente pode modificar livremente.

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

openhands --headless --json -t "Criar uma aplicação Flask simples com endpoint de healthcheck" > openhands-output.jsonl

A página headless descreve --json como um objeto JSON por evento, transmitido como JSONL.

Retomar

openhands --resume
openhands --resume --last
openhands --resume abc123def456

TUI de Navegador ligada ao localhost

openhands web tem por predefinição 0.0.0.0:12000, o que é acessível a partir da rede. Os docs da CLI dizem que essa interface tem a capacidade total da CLI, pelo que uma ligação apenas local é a predefinição mais segura:

openhands web --host 127.0.0.1 --port 12000

ACP para um editor

Os clientes ACP da página IDE são Zed e JetBrains (nativo), Toad (nativo) e VS Code (extensão da comunidade). O editor inicia openhands acp e fala JSON-RPC 2.0 em stdio, usando as definições de LLM guardadas da CLI.

openhands acp
openhands acp --llm-approve
openhands acp --resume --last

Aprovação, códigos de saída e resultados de modelos locais

Sessões interativas perguntam antes das ações. /confirm muda essa política na sessão. --always-approve (alias --yolo) aprova tudo. --llm-approve pergunta apenas para ações que o analisador de segurança pontua como de alto risco. O modo headless é always-approve para toda a execução.

openhands serve --mount-cwd monta o diretório atual em /workspace dentro do contentor da GUI legada. O fluxo da CLI Docker usa SANDBOX_VOLUMES para a mesma fronteira.

Códigos de saída na referência de comandos:

Devstral-Small-2 24B no Ollama parou repetidamente nesta CLI.

A sessão do llama.cpp acima, Qwen3.5-35B-A3B num contexto de 70000 tokens, completou a tarefa IndexNow. Para um agente de terminal que continuava a trabalhar na mesma máquina, o guia rápido do OpenCode é a instalação e configuração do fornecedor.