# Desarrollador de IA OpenHands

## Resumen

[OpenHands](https://github.com/All-Hands-AI/OpenHands) (anteriormente OpenDevin) es una plataforma de código abierto para agentes autónomos de desarrollo de software con IA. Con más de 65K estrellas en GitHub, se ha convertido en una de las herramientas más populares para delegar tareas reales de programación a la IA: escribir código, corregir errores, resolver incidencias en GitHub, ejecutar comandos de shell, navegar por la web e interactuar con su base de código de extremo a extremo.

A diferencia de las herramientas típicas de autocompletado de código, OpenHands ejecuta un **bucle agentivo**: recibe una tarea, planifica, escribe código, lo ejecuta, observa la salida e itera — todo sin intervención humana. Admite decenas de backends LLM incluidos OpenAI, Anthropic Claude, Google Gemini y modelos alojados localmente mediante Ollama o vLLM.

**¿Por qué Clore.ai para OpenHands?**

* OpenHands en sí se basa en CPU y no requiere GPU
* Sin embargo, combinarlo con un **LLM local** (Ollama, vLLM) en el mismo servidor elimina los costes de API y la latencia
* Los servidores GPU asequibles de Clore.ai le permiten ejecutar tanto OpenHands como un modelo local por tan solo **$0.20–$0.35/h**
* Obtiene almacenamiento persistente del área de trabajo, soporte Docker-in-Docker y acceso root completo
* Ideal para tareas autónomas de larga duración que serían costosas mediante APIs de LLM en la nube

**Casos de uso típicos en Clore.ai:**

* Generación autónoma de código a partir de una especificación o descripción de incidencia
* Refactorización masiva de grandes bases de código
* Ejecutar OpenHands + Ollama juntos para un desarrollo agentivo 100% offline
* Automatización de tareas CI/CD sin costes de API

***

## Requisitos

OpenHands requiere acceso al socket de Docker y ejecuta internamente un contenedor runtime aislado. La tabla siguiente cubre las configuraciones recomendadas en Clore.ai:

| Configuración                   | GPU                   | VRAM  | RAM   | Almacenamiento | Precio estimado |
| ------------------------------- | --------------------- | ----- | ----- | -------------- | --------------- |
| **Solo API (sin LLM local)**    | Cualquiera / solo CPU | N/A   | 8 GB  | 20 GB          | \~$0.05–0.10/h  |
| **+ Ollama (Llama 3.1 8B)**     | RTX 3090              | 24 GB | 16 GB | 40 GB          | \~$0.20/h       |
| **+ Ollama (Qwen2.5 32B)**      | RTX 4090              | 24 GB | 32 GB | 60 GB          | \~$0.35/h       |
| **+ vLLM (Llama 3.1 70B)**      | A100 80GB             | 80 GB | 64 GB | 100 GB         | \~$1.10/h       |
| **+ vLLM (Llama 3.3 70B INT4)** | RTX 4090              | 24 GB | 32 GB | 80 GB          | \~$0.35/h       |

> **Nota:** Si solo utiliza las APIs de OpenAI/Anthropic/Gemini, cualquier servidor con ≥8 GB de RAM funciona. La GPU solo es necesaria si quiere ejecutar un LLM local en la misma máquina. Vea el [Guía de comparación de GPU](/guides/guides_v2-es/primeros-pasos/gpu-comparison.md) para más detalles.

**Requisitos de software en el servidor Clore.ai:**

* Docker Engine (preinstalado en todas las imágenes de Clore.ai)
* NVIDIA Container Toolkit (preinstalado en imágenes con GPU)
* Socket de Docker accesible en `/var/run/docker.sock`
* Acceso a internet saliente para descargar imágenes GHCR

***

## Inicio rápido

### Paso 1: Seleccione y conéctese a un servidor Clore.ai

En el [mercado de Clore.ai](https://clore.ai), filtre servidores por:

* RAM ≥ 16 GB (para combinación con LLM local)
* Docker: ✓ habilitado
* Elija la GPU preferida si va a usar un modelo local

Conéctese vía SSH una vez que el servidor esté aprovisionado:

```bash
ssh root@<server-ip> -p <port>
```

### Paso 2: Verifique que Docker está en ejecución

```bash
docker info
ls -la /var/run/docker.sock
```

Ambos comandos deberían tener éxito. Si falta el socket de Docker, contacte con el soporte de Clore.ai o elija una imagen diferente.

### Paso 3: Descargar y ejecutar OpenHands

```bash
# Establecer directorio de trabajo
export WORKSPACE_BASE=$(pwd)/workspace
mkdir -p $WORKSPACE_BASE

# Ejecutar OpenHands (descarga la imagen 0.38 más reciente de GHCR)
docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

### Paso 4: Acceder a la interfaz web

La interfaz está disponible en `http://<server-ip>:3000`

> **Reenvío de puertos en Clore.ai:** En el panel de Clore.ai, asegúrese de que el puerto `3000` esté reenviado/expuesto en la configuración de su servidor. Algunas plantillas restringen puertos externos — consulte la sección "Puertos" en los detalles de su servidor.

En el primer lanzamiento, OpenHands le pedirá que configure un proveedor de LLM.

### Paso 5: Configure su LLM

En la configuración de la interfaz web:

* **Proveedor:** Seleccione OpenAI, Anthropic, Google o Personalizado
* **Clave API:** Ingrese su clave API
* **Modelo:** p. ej., `gpt-4o`, `claude-3-5-sonnet-20241022`, o `ollama/llama3.1`

Para Ollama local (vea la sección de Aceleración GPU más abajo), use:

* Proveedor: `ollama`
* URL base: `http://host.docker.internal:11434`
* Modelo: `ollama/llama3.1:8b`

***

## Configuración

### Variables de entorno

OpenHands puede configurarse completamente mediante variables de entorno pasadas a `docker run`:

```bash
docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 \
  -e LLM_API_KEY=sk-ant-... \
  -e LLM_BASE_URL="" \
  -e SANDBOX_TIMEOUT=120 \
  -e MAX_ITERATIONS=100 \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

| Variable          | Descripción                                                              | Valor por defecto         |
| ----------------- | ------------------------------------------------------------------------ | ------------------------- |
| `LLM_MODEL`       | Identificador del modelo (p. ej. `gpt-4o`, `claude-3-5-sonnet-20241022`) | Establecido en la UI      |
| `LLM_API_KEY`     | Clave API para el proveedor de LLM                                       | Establecido en la UI      |
| `LLM_BASE_URL`    | URL base personalizada (para Ollama, vLLM, LiteLLM)                      | Por defecto del proveedor |
| `SANDBOX_TIMEOUT` | Tiempo de espera del sandbox del agente en segundos                      | `120`                     |
| `MAX_ITERATIONS`  | Máximo de iteraciones del bucle agentivo por tarea                       | `100`                     |
| `SANDBOX_USER_ID` | UID para ejecutar el sandbox como (use `$(id -u)`)                       | `0`                       |
| `LOG_ALL_EVENTS`  | Habilitar registro detallado de eventos (`true`/`false`)                 | `false`                   |

### Archivo de configuración persistente

Puede persistir la configuración montando un directorio de configuración:

```bash
mkdir -p /opt/openhands/config

docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/openhands/config:/app/config \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

### Ejecutar en segundo plano (modo detached)

Para sesiones de larga duración en Clore.ai:

```bash
export WORKSPACE_BASE=/opt/workspace
mkdir -p $WORKSPACE_BASE

docker run -d \
  --name openhands \
  --restart unless-stopped \
  --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 \
  -e LLM_API_KEY=your_api_key_here \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38

# Ver registros
docker logs -f openhands
```

***

## Aceleración GPU (Integración de LLM local)

Aunque OpenHands en sí no usa la GPU, combinarlo con un **LLM local** ejecutado en la GPU de Clore.ai le da un agente autónomo potente, rentable y sin necesidad de APIs.

### Opción A: OpenHands + Ollama (Recomendado para principiantes)

Ejecute Ollama primero y luego apunte OpenHands hacia él:

```bash
# 1. Iniciar Ollama (consulte la guía de Ollama para detalles completos)
docker run -d \
  --name ollama \
  --gpus all \
  -p 11434:11434 \
  -v ollama-data:/root/.ollama \
  ollama/ollama:latest

# 2. Descargar un modelo optimizado para codificación
docker exec ollama ollama pull qwen2.5-coder:7b
# O para más potencia:
docker exec ollama ollama pull llama3.1:8b
docker exec ollama ollama pull deepseek-coder-v2:16b

# 3. Iniciar OpenHands apuntando a Ollama
export WORKSPACE_BASE=/opt/workspace
mkdir -p $WORKSPACE_BASE

docker run -d \
  --name openhands \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=ollama/qwen2.5-coder:7b \
  -e LLM_BASE_URL=http://host.docker.internal:11434 \
  -e LLM_API_KEY=ollama \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

> Vea el [guía de Ollama](/guides/guides_v2-es/modelos-de-lenguaje/ollama.md) completo para la selección de modelos, ajuste de rendimiento y configuración de GPU.

### Opción B: OpenHands + vLLM (Alto rendimiento)

Para máximo rendimiento con modelos más grandes:

```bash
# 1. Iniciar vLLM con un modelo para codificación
docker run -d \
  --name vllm \
  --gpus all \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --max-model-len 16384 \
  --gpu-memory-utilization 0.92

# Espere a que el modelo cargue (~2-5 min)
docker logs -f vllm | grep "Application startup"

# 2. Iniciar OpenHands con backend vLLM
docker run -d \
  --name openhands \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=/opt/workspace \
  -e LLM_MODEL=openai/Qwen/Qwen2.5-Coder-32B-Instruct \
  -e LLM_BASE_URL=http://host.docker.internal:8000/v1 \
  -e LLM_API_KEY=none \
  -v /opt/workspace:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38
```

> Ver el [guía de vLLM](/guides/guides_v2-es/modelos-de-lenguaje/vllm.md) para la configuración completa, opciones de cuantización y configuraciones multi-GPU.

### Modelos locales recomendados para codificación

| Modelo                  | Tamaño | VRAM mínima | Calidad |
| ----------------------- | ------ | ----------- | ------- |
| `qwen2.5-coder:7b`      | 7B     | 8 GB        | ★★★☆☆   |
| `deepseek-coder-v2:16b` | 16B    | 12 GB       | ★★★★☆   |
| `qwen2.5-coder:32b`     | 32B    | 24 GB       | ★★★★☆   |
| `llama3.1:70b`          | 70B    | 48 GB       | ★★★★★   |

***

## Consejos y mejores prácticas

### 1. Use los montajes del área de trabajo con prudencia

Monte su directorio de proyecto real como área de trabajo para que OpenHands pueda editar directamente sus archivos:

```bash
export WORKSPACE_BASE=/opt/my-project
git clone https://github.com/your/repo $WORKSPACE_BASE
```

### 2. Prompts de tarea para mejores resultados

OpenHands funciona mejor con prompts específicos y accionables:

```
✅ Bueno: "Corrige el error de autenticación en src/auth/login.py donde los tokens JWT 
         expiran inmediatamente. El problema está en el cálculo de la expiración del token."

❌ Malo: "Arregla el error"
```

### 3. Monitoree el uso de recursos

```bash
# Ver uso de GPU y memoria
watch -n 2 'nvidia-smi && docker stats --no-stream'
```

### 4. Establezca límites de iteración

Evite que agentes descontrolados consuman demasiados tokens de API:

```bash
-e MAX_ITERATIONS=50  # Limitar a 50 pasos por tarea
```

### 5. Integración con GitHub

OpenHands puede resolver incidencias de GitHub directamente. Configure en la UI:

* Token de GitHub: Su token de acceso personal con `repo` alcance
* OpenHands clonará el repositorio, corregirá la incidencia y creará un PR

### 6. Estimación de costes

Para LLMs basados en API, estime el coste por tarea:

* Corrección simple de bug: \~$0.05–0.15 (Claude Haiku/GPT-4o-mini)
* Funcionalidad compleja: \~$0.50–2.00 (Claude Sonnet/GPT-4o)
* Para más de 100 tareas/día, un LLM local en Clore.ai se amortiza

***

## Solución de problemas

### Permiso denegado en el socket de Docker

```bash
# Error: permiso denegado al intentar conectar con el daemon de Docker
# Solución: asegúrese de que el socket sea accesible
ls -la /var/run/docker.sock
# Debería mostrar: srw-rw---- 1 root docker ...

# Añada su usuario al grupo docker si es necesario
usermod -aG docker $USER
# Luego reinicie la shell o use: newgrp docker
```

### El contenedor sandbox no inicia

```bash
# Compruebe si la imagen runtime es accesible
docker pull ghcr.io/all-hands-ai/runtime:0.38-nikolaik

# Compruebe los límites de tasa de GHCR (puede necesitar autenticarse)
docker login ghcr.io
```

### Puerto 3000 no accesible

```bash
# Verifique que el contenedor esté en ejecución y el puerto esté enlazado
docker ps | grep openhands
docker port openhands

# Compruebe el firewall de Clore.ai — asegúrese de que el puerto 3000 esté en su mapeo de puertos
# En el panel de Clore.ai: Servidor → Puertos → Añadir 3000:3000
```

### Errores de conexión LLM con Ollama

```bash
# Pruebe que Ollama sea accesible desde el contenedor OpenHands
docker exec openhands curl http://host.docker.internal:11434/api/tags

# Si falla, verifique que la bandera --add-host se incluyó en docker run
# También compruebe que el contenedor Ollama esté en ejecución:
docker ps | grep ollama
docker logs ollama | tail -20
```

### El agente entra en bucle indefinidamente

```bash
# Reduzca las iteraciones máximas
docker stop openhands
docker run ... -e MAX_ITERATIONS=30 ...

# O establezca un tiempo de espera
-e SANDBOX_TIMEOUT=60
```

### Falta de memoria (OOM)

```bash
# Comprobar uso de memoria
free -h
docker stats

# Si ejecuta un LLM local, pruebe con un modelo más pequeño
docker exec ollama ollama pull qwen2.5-coder:3b

# O use una versión cuantizada (menos VRAM)
docker exec ollama ollama pull llama3.1:8b-instruct-q4_K_M
```

***

## Lecturas adicionales

* [Repositorio de OpenHands en GitHub](https://github.com/All-Hands-AI/OpenHands) — Código fuente, incidencias y releases
* [Documentación de OpenHands](https://docs.all-hands.dev) — Documentación oficial incluyendo la configuración de LLM
* [Ollama en Clore.ai](/guides/guides_v2-es/modelos-de-lenguaje/ollama.md) — Ejecutar LLMs locales para inferencia de agentes sin coste
* [vLLM en Clore.ai](/guides/guides_v2-es/modelos-de-lenguaje/vllm.md) — Servicio de LLM local de alto rendimiento
* [Guía de comparación de GPU](/guides/guides_v2-es/primeros-pasos/gpu-comparison.md) — Elija la GPU adecuada para su carga de trabajo
* [Discord de OpenHands](https://discord.gg/ESHStjSjD4) — Soporte comunitario y recomendaciones de modelos
* [Leaderboard de SWE-bench](https://www.swebench.com) — Comparar el rendimiento de agentes en incidencias reales de GitHub


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-es/plataformas-y-agentes-de-ia/openhands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.