Inicio Rápido del Asistente de Codificación OpenHands: Instalación, Banderas de la CLI y Ejemplos

OpenHands CLI: Inicio rápido en minutos

Índice

OpenHands es una plataforma de código abierto e agnóstica a modelos para agentes de desarrollo de software impulsados por IA. Permite que un agente se comporte más como un compañero de codificación que como una simple herramienta de autocompletado.

Puede trabajar con archivos, ejecutar comandos en un entorno aislado (sandbox) y utilizar la navegación web cuando sea necesario.

Esta guía de inicio rápido se centra en la CLI de OpenHands, ya que es la forma más rápida de ser productivo desde tu terminal, y se adapta de manera limpia a patrones de automatización como scripts y ejecuciones de CI. Para una visión más amplia del espacio, consulta Herramientas para desarrolladores de IA: La guía completa al desarrollo potenciado por IA.

openhands text user interface

Qué es OpenHands y qué lo diferencia

Un asistente de codificación de IA típicamente te ayuda a generar o editar código utilizando un modelo de lenguaje. OpenHands extiende esa idea hacia un flujo de trabajo “agéntico”: el sistema puede planificar de forma iterativa, tomar acciones (como escribir archivos o ejecutar pruebas), observar resultados y continuar hasta que la tarea esté completa.

OpenHands también es ampliamente conocido como el proyecto anteriormente llamado OpenDevin, y ha crecido hasta convertirse en una plataforma impulsada por la comunidad con múltiples formas de usarlo: una CLI, una interfaz gráfica web local, una interfaz de usuario alojada en la nube y un SDK.

Desde una perspectiva de ingeniería, el diferenciador clave es que OpenHands se construye alrededor de un entorno de ejecución (un sandbox) para que un agente pueda ejecutar comandos y herramientas de forma segura, en lugar de solo producir texto. El artículo de OpenHands describe un entorno de tiempo de ejecución con sandbox de Docker con una shell y capacidad de navegación web, específicamente para soportar patrones de interacción realistas similares a los de un desarrollador.

Instalar OpenHands CLI

OpenHands admite múltiples métodos de instalación. Para la mayoría de los desarrolladores, lo mejor es comenzar con una instalación local de la CLI (iteración rápida) y opcionalmente agregar flujos de trabajo basados en Docker más adelante cuando desees un aislamiento estricto alrededor de la ejecución.

Instalar con uv

La documentación actual de la CLI de OpenHands recomienda instalar con uv, y requiere Python 3.12+.

uv tool install openhands --python 3.12
openhands

La actualización es igualmente sencilla.

uv tool upgrade openhands --python 3.12

Por qué uv importa en la práctica: uv proporciona un mejor aislamiento de tu entorno de proyecto actual y es necesario para los servidores MCP predeterminados.

Instalar el binario CLI independiente

Si deseas un flujo de instalación de “un solo comando”, OpenHands proporciona un script de instalación.

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

En macOS, es posible que debas permitir explícitamente el binario en Privacidad y Seguridad antes de que se ejecute.

Ejecutar vía Docker para aislamiento

Si prefieres mantener la instalación contenida, la documentación de la CLI también muestra un flujo basado en Docker. Este enfoque se basa en montar un directorio al que deseas que OpenHands acceda y pasar tu ID de usuario para evitar la creación de archivos propiedad de root en el espacio de trabajo 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"

Configuración de la primera ejecución y dónde se guardan los ajustes

En la primera ejecución, la CLI te guía a través de la configuración de los ajustes de LLM requeridos y los almacena para futuras sesiones. La documentación de la CLI indica que los ajustes se guardan bajo ~/.openhands/settings.json y el historial de conversaciones se almacena en ~/.openhands/conversations, pero cuando instalé OpenHands hace muy poco, guardó la configuración en ~/.openhands/agent_settings.json, por lo que la documentación quizás no es del todo exacta.

Para una configuración más profunda e integración de herramientas, OpenHands también documenta archivos de configuración adicionales como ~/.openhands/agent_settings.json (ajustes del agente y LLM), ~/.openhands/cli_config.json (preferencias de la CLI) y ~/.openhands/mcp.json (servidores MCP).

Configurar OpenHands con Ollama local y llama.cpp

OpenHands funciona con cualquier backend local compatible con OpenAI: Ollama, LocalAI, llama.cpp y otros. Si no estás seguro de cuál usar, consulta Ollama vs vLLM vs LM Studio: La mejor forma de ejecutar LLMs localmente para una comparación.

Cuando inicias OpenHands por primera vez, te muestra la página de ajustes. Cuando ya has pasado por esta etapa de primera vez, puedes abrir esta página nuevamente escribiendo /settings y luego ctrl+j. Ahora escribe:

  • en el campo Custom Model: ollama/devstral-small-2:24b, o el que sea tu modelo local favorito,
  • y en el campo Base Url: http://localhost:11434

openhands settings ollama mistral

Para una referencia rápida de comandos de Ollama, consulta la Hoja de trucos de la CLI de Ollama: servir, ejecutar, ps y gestión de modelos.

Para editar el archivo de configuración de OpenHands manualmente, por ejemplo si no te gusta cómo se ve la página de ajustes, ejecuta:

nano ~/.openhands/agent_settings.json

o si prefieres un editor con más interfaz gráfica:

gedit GUI ~/.openhands/agent_settings.json

Hay una propiedad llm en dos lugares, los he configurado para que tengan estas subpropiedades, entre otras, para apuntar a Ollama:

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

Para apuntar OpenHands a una instancia local de llama.cpp - lo mismo, en dos lugares:

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

Para conectarme a llama.cpp configuré:

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

y estaba iniciando llama.cpp con el comando (consulta Inicio rápido de llama.cpp con CLI y servidor para detalles de las banderas):

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

OpenHands pudo conectarse a él y completar mi solicitud de prueba crea para mí una herramienta de CLI en Go que invoque los endpoints indexnow de Bing y otros motores de búsqueda para notificar sobre cambios en mi sitio web exitosamente, con código fuente, ejecutable y README.md.

Cómo funciona la CLI de OpenHands en la práctica

El comando predeterminado openhands inicia una experiencia de terminal interactiva. OpenHands proporciona una paleta de comandos y comandos durante la sesión para que puedas guiar al agente rápidamente mientras trabaja.

Los controles interactivos útiles que debes conocer desde el principio incluyen abrir la paleta de comandos, pausar al agente y salir de la aplicación.

  • Ctrl+P abre la paleta de comandos.
  • Esc pausa al agente en ejecución.
  • Ctrl+Q o /exit sale de la CLI.

Dentro de la CLI, OpenHands también soporta comandos con prefijo de barra como /help, /new y /condense, lo cual es valioso si deseas gestionar conversaciones largas sin reiniciar.

OpenHands no se detiene en una interfaz de terminal. La CLI incluye múltiples interfaces que se adaptan bien a diferentes flujos de trabajo de desarrollo:

  • Modo headless para automatización y CI.
  • Interfaz web para ejecutar la experiencia de la CLI en un navegador.
  • Servidor GUI para la aplicación web local completa, iniciada vía Docker.
  • Integración de IDE vía ACP para flujos de trabajo basados en editor.

Parámetros de línea de comandos principales que realmente usarás

A alto nivel, la CLI de OpenHands sigue esta forma:

openhands [OPTIONS] [COMMAND]

Esto incluye opciones globales (cosas como tareas, reanudar, headless), además de subcomandos (serve, web, cloud, acp, mcp, login, logout).

Opciones principales para el trabajo diario

Las opciones globales más comúnmente utilizadas son:

  • -t, --task para iniciar la conversación con una tarea inicial.
  • -f, --file para iniciar desde un archivo, lo cual es útil cuando deseas tareas comprometidas al control de versiones.
  • --resume [ID] y --last para continuar ejecuciones anteriores.
  • --headless para ejecución no interactiva, típicamente en automatización.
  • --json para transmitir salida JSONL en modo headless para análisis de máquina.

La seguridad y las aprobaciones también son de primera clase:

  • --always-approve aprueba automáticamente acciones sin solicitar confirmación.
  • --llm-approve utiliza un analizador de seguridad basado en LLM para la aprobación de acciones.

Configuración de modelo y proveedor mediante variables de entorno

OpenHands soporta variables de entorno para la configuración del modelo:

  • LLM_API_KEY establece tu clave de API del proveedor.
  • LLM_MODEL y LLM_BASE_URL pueden aplicarse como sobrescrituras cuando ejecutes openhands --override-with-envs.

Ejemplo de flujo de sobrescritura:

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="tu-clave-api"
openhands --override-with-envs

OpenHands indica explícitamente que las sobrescrituras aplicadas con --override-with-envs no se persisten.

Subcomandos que vale la pena conocer

No necesitas cada subcomando desde el día uno, pero estos son los que surgen rápidamente:

  • openhands serve lanza el servidor GUI completo usando Docker, típicamente accesible en http://localhost:3000, con opciones como --mount-cwd y --gpu.
  • openhands web lanza la CLI como una aplicación web accesible desde el navegador, con puerto predeterminado 12000.
  • openhands login autentica con OpenHands Cloud y obtiene tus ajustes.
  • openhands cloud crea una nueva conversación en OpenHands Cloud desde la CLI.

Ejemplos de copiar y pegar que puedes usar inmediatamente

La forma más rápida de obtener valor de OpenHands es tratarlo como un agente de codificación impulsado por tareas. Mantén las tareas precisas, incluye nombres de archivos y pide pruebas o verificación cuando corresponda.

Iniciar una sesión de codificación interactiva con una tarea inicial

Esta es la “experiencia predeterminada del desarrollador” y uno de los patrones más comunes.

openhands -t "Corregir el bug en auth.py y agregar una prueba de regresión"

La documentación de la CLI de OpenHands muestra esta idea exacta para inicializar una sesión con -t.

Iniciar una tarea desde un archivo

Usar un archivo es útil cuando deseas repetibilidad, revisión del equipo o reutilización en CI.

cat > task.txt << 'EOF'
Refactorizar el módulo de conexión a la base de datos.
Agregar pruebas unitarias y asegurar que la suite de pruebas pase.
EOF

openhands -f task.txt

El Inicio Rápido de la CLI soporta explícitamente iniciar desde un archivo de tarea con -f.

Ejecutar en modo headless para CI o automatización

El modo headless se ejecuta sin la interfaz interactiva y está diseñado para pipelines de CI y scripting automatizado.

openhands --headless -t "Agregar pruebas unitarias para auth.py y ejecutarlas"

Dos realidades de ingeniería importantes aquí:

  • El modo headless requiere --task o --file.
  • El modo headless siempre se ejecuta en modo siempre-aprobar y no puede cambiarse, y --llm-approve no está disponible en modo headless. Trátalo como una automatización potente y ejecútalo en un entorno controlado.

Para integrar con análisis de logs u otras herramientas, habilita la salida JSONL:

openhands --headless --json -t "Crear una aplicación Flask simple con endpoint de salud" > openhands-output.jsonl

OpenHands documenta --json como transmisión de eventos JSONL en modo headless y muestra redirigir la salida a un archivo.

Reanudar trabajo sin perder el contexto

Reanudar es crítico una vez que comienzas a usar OpenHands para cambios no triviales.

Listar conversaciones recientes:

openhands --resume

Reanudar la más reciente:

openhands --resume --last

O reanudar un ID de conversación específico:

openhands --resume abc123def456

Estos flujos están documentados en la referencia de comandos de la CLI y la guía “Reanudar Conversaciones”.

Ejecutar la CLI en un navegador cuando lo necesites

openhands web inicia una CLI accesible vía web (puerto predeterminado 12000).

openhands web

Si estás ejecutando localmente, vincular solo a localhost es un predeterminado sensato:

openhands web --host 127.0.0.1 --port 12000

OpenHands advierte que exponer la interfaz web a la red requiere las medidas de seguridad apropiadas, ya que proporciona acceso completo a las capacidades de OpenHands.

Seguridad, solución de problemas y bordes afilados

El palanca de seguridad más importante en la CLI de OpenHands son las aprobaciones:

  • La CLI interactiva puede solicitar confirmación antes de acciones sensibles, y puedes configurar ajustes de confirmación durante la sesión.
  • --always-approve elimina la fricción pero también elimina salvaguardas.
  • --llm-approve agrega un analizador basado en LLM para aprobaciones.
  • El modo headless siempre aprueba, así que resérvalo para automatización en entornos controlados.

Al trabajar con código local, prefiere patrones de acceso explícitos y de privilegios mínimos:

  • Para el servidor GUI, openhands serve --mount-cwd monta tu directorio actual en /workspace para que el agente pueda leer y modificar los archivos de tu proyecto.
  • Para ejecuciones de CLI basadas en Docker, usa SANDBOX_VOLUMES para definir exactamente qué directorios puede acceder OpenHands.

Si tienes directorios de estado de OpenHands más antiguos, OpenHands indica una ruta de migración de ~/.openhands-state a ~/.openhands en la documentación de configuración local y guía de solución de problemas.

Finalmente, si estás integrando OpenHands en scripts, los códigos de salida se documentan como:

  • 0 éxito
  • 1 error o tarea fallida
  • 2 argumentos inválidos

Mi experiencia con OpenHands

Para mí, OpenHands funcionó bien, pero no siempre… Intenté hacerlo funcionar con Devstral-Small-2 alojado en Ollama, y se detenía constantemente.

OpenHands with Ollama-hosted Devstral-Small-2.

Aunque OpenHands funcionó bien con Qwen 3.5 35b alojado localmente en llama.cpp. Hasta ahora, para mí, OpenCode es mucho más confiable.