Inicio rápido de la CLI de OpenHands: instalación, banderas y modo headless

OpenHands es un agente de código de código abierto que edita archivos y ejecuta comandos en un entorno aislado (sandbox). Esta guía rápida de CLI se verificó el 26/10/2026 contra el paquete 1.16.0.

El paquete en PyPI es openhands 1.16.0, subido el 8 de mayo de 2026, fijado a openhands-sdk==1.21.0. Su README de etiqueta requiere Python 3.12 y uv 0.11.6 o posterior. El README de la rama predeterminada de OpenHands-CLI indica que ese repositorio ya no se mantiene activamente y redirige las nuevas instalaciones a Agent Canvas. El modo headless y openhands acp siguen formando parte del conjunto de comandos de la versión 1.16.0.

La guía de herramientas de desarrollo de IA sigue la línea de los demás agentes de terminal de este sitio. Esta página se centra en la CLI de OpenHands: instalación, archivos de configuración, URL de modelos locales y las banderas que un guion pasa realmente.

Qué es la CLI

Un asistente de código de IA suele generar o editar código a partir de un indicio. OpenHands extiende esto en un bucle de agente: planificar, realizar una acción como escribir un archivo o ejecutar una prueba, observar el resultado y continuar. El proyecto se llamaba anteriormente OpenDevin. El artículo de OpenHands describe un tiempo de ejecución aislado mediante Docker con un shell y navegación web, que es el modelo de ejecución que la CLI sigue encapsulando.

La versión 1.16.0 documenta cinco formas de ejecutar ese bucle.

Agent Canvas, la instalación que el proyecto documenta ahora

El 3 de junio de 2026, el FAQ de OpenHands puso la UI de terminal en modo de mantenimiento hasta el 1 de octubre de 2026, y declaró que el modo headless y ACP se mantendrían con soporte completo. La GUI local (openhands serve) permanecería en mantenimiento hasta que Agent Canvas pudiera ejecutar entornos aislados efímeros. Dicho FAQ define el mantenimiento como actualizaciones de dependencias, correcciones de errores críticos y nuevos LLM. El repositorio principal de OpenHands publicó Agent Canvas 1.33.0 el 23 de octubre de 2026.

agent-canvas inicia la UI actual y su backend. openhands serve inicia la GUI legacy y no inicia Agent Canvas.

Agent Canvas necesita Node.js 24 o posterior y uv. Una primera ejecución sin instalación global:

npx @openhands/agent-canvas

El proceso escucha en http://localhost:8000. Cerrar esa terminal detiene el backend local. Una instalación global es npm install -g @openhands/agent-canvas, seguido de agent-canvas. La vía de npm ejecuta el servidor del agente como su usuario, por lo que el agente puede actuar sobre archivos locales con los permisos de su cuenta.

La vía de Docker publica el puerto solo en localhost y monta un directorio de proyectos:

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

El contenedor sirve la UI en http://localhost:8000/canvas. El volumen nombrado openhands-data conserva la configuración tras --rm. En Linux, montar por enlace ~/.openhands en esta imagen falla con unable to open database file: el usuario del contenedor es UID 10001, y un directorio del host suele pertenecer a su propio UID. La página de instalación usa el volumen nombrado por esa razón. La configuración ya presente en ~/.openhands no se copia en un volumen nuevo.

Instalar la CLI de OpenHands

Use la CLI cuando aún desee openhands --headless o openhands acp. El paquete rueda publicado se instala solo en Python 3.12 (==3.12.* en PyPI). uv debe ser 0.11.6 o posterior. En Windows, la página de instalación indica ejecutar los comandos en WSL (Ubuntu).

Instalar con uv

uv tool install openhands --python 3.12
openhands

Actualizar con la misma fijación de intérprete:

uv tool upgrade openhands --python 3.12

La página de configuración local indica que uv es lo que aísla la CLI del entorno virtual del proyecto, y que los servidores MCP predeterminados lo requieren.

Instalar el binario independiente

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

En macOS, un cuadro de diálogo de Gatekeeper puede bloquear el binario (“No se puede abrir openhands porque Apple no puede comprobar si contiene software malicioso”). La vía de la página de instalación es Ajustes del Sistema, Privacidad y Seguridad, luego Permitir de Todos Modos bajo Seguridad, y luego ejecutar openhands de nuevo.

Ejecutar la CLI mediante Docker

El contenedor de la página de instalación fija AGENT_SERVER_IMAGE_TAG en la imagen de agent-server. El uv tool install openhands dentro del contenedor es la CLI de PyPI. La etiqueta en ese ejemplo, verificada para esta página, es 1.26.0-python. Copias más antiguas de este comando usaban 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) hace que el usuario del sandbox coincida con el usuario del host, de modo que el agente no deje archivos con propiedad de root en el espacio de trabajo montado. SANDBOX_VOLUMES es el directorio al que el agente puede acceder.

OPENHANDS_VERSION selecciona la versión de la imagen de Docker para openhands serve. No cambia la versión de la CLI de PyPI.

Archivos de configuración

En el primer arranque, la CLI pregunta por la configuración del modelo y la escribe bajo ~/.openhands/. El README de la 1.16.0 y la referencia de comandos nombran estos archivos:

La página de instalación sigue indicando a los usuarios de Docker preparar ~/.openhands/settings.json. El README de la CLI y AgentStore en el árbol de la 1.16.0 persisten la especificación del agente en agent_settings.json. Una instalación de la CLI que omitió el nombre de archivo de la página de instalación y escribió agent_settings.json coincide con esa fuente.

create_and_save_from_settings construye dos objetos LLM a partir del mismo modelo, clave API y URL base: uno para el agente y otro para el condensador de resumen. Por eso un archivo guardado repite los campos llm. Edite el archivo del agente con cualquier editor:

nano ~/.openhands/agent_settings.json

LLM_API_KEY, LLM_MODEL y LLM_BASE_URL se ignoran a menos que se opte por ello. La sobrescritura no se guarda:

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

OPENHANDS_CLOUD_URL fija el servidor de nube predeterminado. Los comandos cloud y login usan https://app.all-hands.dev de forma predeterminada cuando esa variable no está configurada.

Las actualizaciones desde una CLI anterior a la 1.0.0 necesitan volver a introducir la configuración. La página de instalación indica que el formato de configuración cambió en la 1.0.0.

Modelos locales

La guía de LLM local fechada el 21 de mayo de 2026 recomienda Qwen3.6-35B-A3B como el primer modelo local a probar. Pide una GPU con al menos 24 GB de VRAM para una versión cuantizada, o un Mac con Apple Silicon con al menos 64 GB de memoria unificada. La misma página indica fijar la longitud de contexto a al menos 22000 tokens, y que el valor predeterminado de Ollama de 4096 es demasiado pequeño para el indicio del sistema.

Cuando el agente nunca llama a herramientas, la guía trata eso como un límite del modelo y cita informes de la comunidad para qwen2.5-coder-14b-instruct y qwopus3.5-27b-v3. La comparación de autoalojamiento local es la tabla servidor por servidor cuando Ollama, vLLM, LM Studio o LocalAI siga siendo una opción abierta.

Ollama

El inicio de Ollama de la guía fija la longitud de contexto antes de ollama serve. La hoja de referencia de la CLI de Ollama cubre serve, run y ps junto a esa variable.

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

Para OpenHands ejecutándose en Docker, la configuración de la guía es el modelo personalizado openai/qwen3.6:35b-a3b, URL base http://host.docker.internal:11434/v1 y cualquier clave API de marcador de posición. Una CLI ejecutándose en el mismo host que Ollama usa http://127.0.0.1:11434/v1 en lugar de host.docker.internal. Linux LM Studio y otros servidores solo de bucle de retorno (loopback) son inalcanzables desde un contenedor en 127.0.0.1; la comprobación de la guía es habilitar el servicio en la red local y hacer curl a host.docker.internal desde dentro del contenedor.

La página de terminal abre esa pantalla con Ctrl+P y luego Ajustes. Un perfil de CLI guardado usó un id de modelo ollama/ y una URL base sin /v1:

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

Esa sesión de Devstral-Small-2 fue la que siguió deteniéndose. Los campos escritos para ella, tanto en el LLM del agente como en el LLM del condensador, fueron:

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

llama.cpp y vLLM

llama.cpp usó el prefijo compatible con OpenAI y una URL base /v1, de nuevo en ambos objetos LLM:

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

El comando del servidor, con las banderas cubiertas en el inicio rápido de llama.cpp, fue:

./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 ese servidor, la CLI completó un cliente IndexNow en Go: código fuente, un ejecutable y un README. El texto de la tarea fue 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.

El ejemplo de vLLM de la guía de LLM local para el modelo Qwen3.6 más nuevo es un servicio de dos GPUs. El inicio rápido de vLLM pasa por las banderas de vllm serve y las comprobaciones de memoria insuficiente. La cadena de modelo de OpenHands coincidente de la guía es openai/Qwen3.6-35B-A3B, con URL base http://host.docker.internal:8000/v1 y la misma --api-key con la que se inició el servidor (mykey en su ejemplo).

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 interactivos

openhands sin subcomando abre la UI de terminal. La página de terminal lista estos controles:

Comandos de barra desde la referencia de comandos: /help, /new, /history, /confirm, /condense, /skills, /feedback, /exit. Los cambios de modelo desde la entrada de Ajustes de la paleta se aplican sin reinicio. --exit-without-confirmation omite el cuadro de diálogo de salida. --exp selecciona la UI de texto y está documentado como una bandera de compatibilidad porque esa UI ya es la predeterminada.

Banderas y subcomandos

openhands [OPCIONES] [COMANDO]

Opciones globales en la referencia de comandos, verificadas contra argparsers/util.py en la etiqueta 1.16.0 para las banderas de aprobación y entorno:

--always-approve y --llm-approve no pueden combinarse. El modo interactivo predeterminado pregunta antes de las acciones.

Subcomandos que aparecen cuando la TUI no es suficiente:

• openhands serve inicia la GUI legacy en Docker. --mount-cwd monta el directorio actual en /workspace. --gpu activa nvidia-docker.
• openhands web sirve la CLI en un navegador. --host es 0.0.0.0 por defecto, --port es 12000, --debug está desactivado.
• openhands acp habla el Protocolo de Cliente de Agente en stdio. Banderas: --resume, --last, --always-approve, --llm-approve, --streaming.
• openhands cloud -t "tarea" abre una conversación en la nube. --server-url sobrescribe https://app.all-hands.dev.
• openhands login y openhands logout gestionan esa cuenta en la nube. logout sin --server-url cierra sesión de todos los servidores guardados.
• openhands mcp gestiona servidores: add, list, get, remove, enable, disable. add requiere --transport de http, sse o stdio.

Un servidor MCP del README de la 1.16.0:

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

Ejemplos

Tarea interactiva

openhands -t "Fix the bug in auth.py and add a regression test"

Archivo de tarea

cat > task.txt << 'EOF'
Refactor the database connection module.
Add unit tests and ensure the test suite passes.
EOF

openhands -f task.txt

Headless, incluyendo JSONL

El modo headless requiere --task o --file. Siempre se ejecuta como siempre-aprobar, y --llm-approve se rechaza allí. Trate el directorio de trabajo como uno que el agente puede modificar libremente.

openhands --headless -t "Add unit tests for auth.py and run them"

openhands --headless --json -t "Create a simple Flask app with healthcheck endpoint" > openhands-output.jsonl

La página de headless describe --json como un objeto JSON por evento, transmitido como JSONL.

Reanudar

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

TUI de navegador unida a localhost

openhands web es 0.0.0.0:12000 por defecto, lo cual es alcanzable desde la red. Los documentos de la CLI dicen que esa interfaz tiene toda la capacidad de la CLI, por lo que una unión solo local es el valor predeterminado más seguro:

openhands web --host 127.0.0.1 --port 12000

ACP para un editor

Los clientes ACP de la página de IDE son Zed y JetBrains (nativo), Toad (nativo) y VS Code (extensión de la comunidad). El editor inicia openhands acp y habla JSON-RPC 2.0 por stdio, usando la configuración de LLM guardada de la CLI.

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

Aprobación, códigos de salida y resultados de modelos locales

Las sesiones interactivas preguntan antes de las acciones. /confirm cambia esa política en la sesión. --always-approve (alias --yolo) aprueba todo. --llm-approve pregunta solo por las acciones que el analizador de seguridad puntúa como de alto riesgo. El modo headless es siempre-aprobar para toda la ejecución.

openhands serve --mount-cwd monta el directorio actual en /workspace dentro del contenedor de la GUI legacy. El flujo de la CLI de Docker usa SANDBOX_VOLUMES para el mismo límite.

Códigos de salida en la referencia de comandos:

Devstral-Small-2 24B en Ollama se detuvo repetidamente en esta CLI.

La sesión de llama.cpp anterior, Qwen3.5-35B-A3B en un contexto de 70000 tokens, completó la tarea IndexNow. Para un agente de terminal que siguió trabajando en la misma máquina, el inicio rápido de OpenCode es la instalación y configuración del proveedor.