> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-es/plataformas-y-agentes-de-ia/openhands.md).

# Desarrollador de IA OpenHands

Despliega OpenHands (antes OpenDevin) en Clore.ai: ejecuta un ingeniero de software de IA totalmente autónomo en servidores de nube GPU asequibles para programar, depurar y resolver issues de GitHub.

## Descripción general

[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 65 mil 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 issues de GitHub, ejecutar comandos de shell, navegar por la web e interactuar con tu base de código de extremo a extremo.

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

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

* OpenHands en sí está basado en CPU y no requiere una GPU
* Sin embargo, combinarlo con un **LLM local** (Ollama, vLLM) en el mismo servidor elimina los costos de API y la latencia
* Los servidores GPU asequibles de Clore.ai te permiten ejecutar tanto OpenHands como un modelo local por tan solo **$0.20–$0.35/hora**
* Obtienes almacenamiento persistente del espacio de trabajo, compatibilidad con Docker-in-Docker y acceso root completo
* Ideal para tareas autónomas de larga duración que resultarí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 un problema
* Refactorización masiva de grandes bases de código
* Ejecutar OpenHands + Ollama juntos para desarrollo agéntico 100 % sin conexión
* Automatización de tareas de CI/CD sin costos de API

***

## Requisitos

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

| Configuración                   | GPU                   | VRAM  | RAM   | Almacenamiento | Precio est.                               |
| ------------------------------- | --------------------- | ----- | ----- | -------------- | ----------------------------------------- |
| **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.07–0.21/h                              |
| **+ Ollama (Qwen2.5 32B)**      | RTX 4090              | 24 GB | 32 GB | 60 GB          | $0.14–0.42/h                              |
| **+ vLLM (Llama 3.1 70B)**      | A100 80GB             | 80 GB | 64 GB | 100 GB         | [bare metal](https://clore.ai/bare-metal) |
| **+ vLLM (Llama 3.3 70B INT4)** | RTX 4090              | 24 GB | 32 GB | 80 GB          | $0.14–0.42/h                              |

> **Nota:** Si solo usas APIs de OpenAI/Anthropic/Gemini, cualquier servidor con ≥8 GB de RAM funciona. La GPU solo es necesaria si quieres ejecutar un LLM local en la misma máquina. Consulta la [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 de Clore.ai:**

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

***

## Inicio rápido

### Paso 1: Selecciona y conéctate a un servidor de Clore.ai

En la [mercado de Clore.ai](https://clore.ai), filtra los servidores por:

* RAM ≥ 16 GB (para la combinación con LLM local)
* Docker: ✓ habilitado
* Elige tu GPU preferida si usas un modelo local

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

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

### Paso 2: Verifica que Docker esté en ejecución

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

Ambos comandos deberían ejecutarse correctamente. Si falta el socket de Docker, contacta al soporte de Clore.ai o elige una imagen diferente.

### Paso 3: Descarga y ejecuta OpenHands

```bash
# Configura el directorio del espacio de trabajo
export WORKSPACE_BASE=$(pwd)/workspace
mkdir -p $WORKSPACE_BASE

# Ejecuta 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: Accede a la interfaz web

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

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

En el primer inicio, OpenHands te pedirá configurar un proveedor de LLM.

### Paso 5: Configura tu LLM

En la configuración de la interfaz web:

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

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

* 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 predeterminado         |
| ----------------- | ------------------------------------------------------------------------ | ---------------------------- |
| `LLM_MODEL`       | Identificador del modelo (p. ej. `gpt-4o`, `claude-3-5-sonnet-20241022`) | Configurado en la interfaz   |
| `LLM_API_KEY`     | Clave API para el proveedor de LLM                                       | Configurado en la interfaz   |
| `LLM_BASE_URL`    | URL base personalizada (para Ollama, vLLM, LiteLLM)                      | Predeterminado del proveedor |
| `SANDBOX_TIMEOUT` | Tiempo de espera del entorno aislado del agente en segundos              | `120`                        |
| `MAX_ITERATIONS`  | Máximo de iteraciones del bucle agéntico por tarea                       | `100`                        |
| `SANDBOX_USER_ID` | UID con el que ejecutar el entorno aislado (usa `$(id -u)`)              | `0`                          |
| `LOG_ALL_EVENTS`  | Habilita el registro detallado de eventos (`true`/`false`)               | `false`                      |

### Archivo de configuración persistente

Puedes 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
```

### Ejecución en segundo plano (modo desacoplado)

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** que se ejecute en la GPU de Clore.ai te da un agente autónomo potente, rentable y sin API.

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

Ejecuta primero Ollama y luego apunta OpenHands hacia él:

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

# 2. Descarga un modelo optimizado para programació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. Inicia 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
```

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

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

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

```bash
# 1. Inicia vLLM con un modelo de programació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

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

# 2. Inicia OpenHands con el backend de 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
```

> Consulta la [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 programar

| 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. Usa los montajes del espacio de trabajo con inteligencia

Monta el directorio real de tu proyecto como espacio de trabajo para que OpenHands pueda editar tus archivos directamente:

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

### 2. Redacción de tareas para obtener los mejores resultados

OpenHands funciona mejor con instrucciones específicas y accionables:

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

❌ Mal: "Corrige el error"
```

### 3. Monitorea el uso de recursos

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

### 4. Establece límites de iteraciones

Evita que los 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 issues de GitHub directamente. Configúralo en la interfaz:

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

### 6. Estimación de costos

Para LLM basados en API, estima el costo por tarea:

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

***

## Solución de problemas

### Permiso denegado para el socket de Docker

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

# Añade tu usuario al grupo docker si es necesario
usermod -aG docker $USER
# Luego reinicia la shell o usa: newgrp docker
```

### El contenedor del entorno aislado no se inicia

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

# Comprueba los límites de tasa de GHCR (puede que necesites autenticarte)
docker login ghcr.io
```

### El puerto 3000 no es accesible

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

# Comprueba el cortafuegos de Clore.ai — asegúrate de que el puerto 3000 esté en tu mapeo de puertos
# En el panel de Clore.ai: Server → Ports → Añadir 3000:3000
```

### Errores de conexión al LLM con Ollama

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

# Si falla, verifica que la opción --add-host se incluyó en docker run
# Comprueba también que el contenedor de Ollama esté en ejecución:
docker ps | grep ollama
docker logs ollama | tail -20
```

### El agente entra en bucle indefinidamente

```bash
# Reduce el máximo de iteraciones
docker stop openhands
docker run ... -e MAX_ITERATIONS=30 ...

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

### Sin memoria (OOM)

```bash
# Comprueba el uso de memoria
free -h
docker stats

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

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

***

## Lecturas adicionales

* [Repositorio de GitHub de OpenHands](https://github.com/All-Hands-AI/OpenHands) — Código fuente, issues y versiones
* [Documentación de OpenHands](https://docs.all-hands.dev) — Documentación oficial, incluida la configuración de LLM
* [Ollama en Clore.ai](/guides/guides_v2-es/modelos-de-lenguaje/ollama.md) — Ejecuta LLM locales para inferencia agéntica gratuita
* [vLLM en Clore.ai](/guides/guides_v2-es/modelos-de-lenguaje/vllm.md) — Servicio local de LLM de alto rendimiento
* [Guía de comparación de GPU](/guides/guides_v2-es/primeros-pasos/gpu-comparison.md) — Elige la GPU adecuada para tu carga de trabajo
* [Discord de OpenHands](https://discord.gg/ESHStjSjD4) — Soporte de la comunidad y recomendaciones de modelos
* [Clasificación de SWE-bench](https://www.swebench.com) — Compara el rendimiento de agentes en issues reales de GitHub


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.