# OpenHands AI Developer

## Обзор

[OpenHands](https://github.com/All-Hands-AI/OpenHands) (ранее OpenDevin) — это платформа с открытым исходным кодом для автономных агентов разработки ПО с использованием ИИ. С более чем 65 тысячами звёзд на GitHub она стала одним из самых популярных инструментов для делегирования реальных программных задач ИИ — написание кода, исправление ошибок, решение проблем на GitHub, выполнение shell-команд, просмотр веба и взаимодействие с вашим кодовой базой от начала до конца.

В отличие от типичных инструментов автозаполнения кода, OpenHands запускает **агентную петлю**: он принимает задачу, планирует, пишет код, выполняет его, наблюдает результат и итеративно повторяет — всё без вмешательства человека. Поддерживает десятки LLM-бэкендов, включая OpenAI, Anthropic Claude, Google Gemini и локально размещённые модели через Ollama или vLLM.

**Почему Clore.ai для OpenHands?**

* Сам OpenHands работает на CPU и не требует GPU
* Тем не менее, сочетание его с **локальной LLM** (Ollama, vLLM) на том же сервере устраняет расходы на API и задержки
* Доступные GPU‑серверы Clore.ai позволяют запускать одновременно OpenHands и локальную модель всего за **$0.20–$0.35/ч**
* Вы получаете постоянное хранилище рабочего пространства, поддержку Docker-in-Docker и полный root‑доступ
* Идеально для длительных автономных задач, которые через облачные LLM API были бы дорогими

**Типичные сценарии использования на Clore.ai:**

* Автономная генерация кода по спецификации или описанию issue
* Массовое рефакторинг больших кодовых баз
* Совместный запуск OpenHands + Ollama для 100% офлайн‑агентной разработки
* Автоматизация CI/CD задач без затрат на API

***

## Требования

OpenHands требует доступа к Docker‑сокету и внутри запускает сандбокс‑runtime контейнер. В таблице ниже приведены рекомендуемые настройки на Clore.ai:

| Конфигурация                             | GPU                | VRAM  | ОЗУ   | Хранилище | Оцениваемая цена |
| ---------------------------------------- | ------------------ | ----- | ----- | --------- | ---------------- |
| **Только через API (без локальной LLM)** | Любой / только CPU | N/A   | 8 ГБ  | 20 ГБ     | \~$0.05–0.10/час |
| **+ Ollama (Llama 3.1 8B)**              | RTX 3090           | 24 ГБ | 16 ГБ | 40 ГБ     | ≈ $0.20/ч        |
| **+ Ollama (Qwen2.5 32B)**               | RTX 4090           | 24 ГБ | 32 ГБ | 60 ГБ     | ≈ $0.35/ч        |
| **+ vLLM (Llama 3.1 70B)**               | A100 80GB          | 80 ГБ | 64 ГБ | 100 ГБ    | ≈ $1.10/ч        |
| **+ vLLM (Llama 3.3 70B INT4)**          | RTX 4090           | 24 ГБ | 32 ГБ | 80 ГБ     | ≈ $0.35/ч        |

> **Примечание:** Если вы используете только OpenAI/Anthropic/Gemini API, подойдёт любой сервер с ≥8 ГБ ОЗУ. GPU требуется только если вы хотите запускать локальную LLM на той же машине. См. [Руководство по сравнению GPU](/guides/guides_v2-ru/nachalo-raboty/gpu-comparison.md) для подробностей.

**Требования к ПО на сервере Clore.ai:**

* Docker Engine (предустановлен на всех образах Clore.ai)
* NVIDIA Container Toolkit (предустановлен на GPU‑образах)
* Docker‑сокет доступен по адресу `/var/run/docker.sock`
* Исходящий доступ в интернет для загрузки образов с GHCR

***

## Быстрый старт

### Шаг 1: Выберите и подключитесь к серверу Clore.ai

В [маркетплейсе Clore.ai](https://clore.ai), фильтруйте серверы по:

* ОЗУ ≥ 16 ГБ (для комбинации с локальной LLM)
* Docker: ✓ включён
* Выберите предпочитаемый GPU, если используете локальную модель

Подключитесь по SSH после Provision сервера:

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

### Шаг 2: Убедитесь, что Docker запущен

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

Обе команды должны выполниться успешно. Если Docker‑сокет отсутствует, свяжитесь со службой поддержки Clore.ai или выберите другой образ.

### Шаг 3: Загрузите и запустите OpenHands

```bash
# Установите директорию рабочего пространства
export WORKSPACE_BASE=$(pwd)/workspace
mkdir -p $WORKSPACE_BASE

# Запустите OpenHands (загружает последний образ 0.38 с 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
```

### Шаг 4: Доступ к веб‑интерфейсу

Интерфейс доступен по адресу `http://<server-ip>:3000`

> **Проброс портов в Clore.ai:** В панели Clore.ai убедитесь, что порт `3000` проброшен/открыт в конфигурации сервера. Некоторые шаблоны ограничивают внешние порты — проверьте раздел «Порты» в деталях сервера.

При первом запуске OpenHands попросит вас настроить поставщика LLM.

### Шаг 5: Настройте вашу LLM

В настройках веб‑интерфейса:

* **Поставщик:** Выберите OpenAI, Anthropic, Google или Custom
* **API Key:** Введите ваш API‑ключ
* **Модель:** например, `gpt-4o`, `claude-3-5-sonnet-20241022`, или `ollama/llama3.1`

Для локального Ollama (см. раздел про ускорение на GPU ниже) используйте:

* Поставщик: `ollama`
* Базовый URL: `http://host.docker.internal:11434`
* Модель: `ollama/llama3.1:8b`

***

## Конфигурация

### Переменные окружения

OpenHands можно полностью настроить через переменные окружения, передаваемые в `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
```

| Переменная        | Описание                                                               | По умолчанию            |
| ----------------- | ---------------------------------------------------------------------- | ----------------------- |
| `LLM_MODEL`       | Идентификатор модели (например `gpt-4o`, `claude-3-5-sonnet-20241022`) | Установлено в UI        |
| `LLM_API_KEY`     | API‑ключ для поставщика LLM                                            | Установлено в UI        |
| `LLM_BASE_URL`    | Пользовательский базовый URL (для Ollama, vLLM, LiteLLM)               | По умолчанию поставщика |
| `SANDBOX_TIMEOUT` | Таймаут сандбокса агента в секундах                                    | `120`                   |
| `MAX_ITERATIONS`  | Макс. число итераций агентной петли на задачу                          | `100`                   |
| `SANDBOX_USER_ID` | UID, под которым запускается сандбокс (используйте `$(id -u)`)         | `0`                     |
| `LOG_ALL_EVENTS`  | Включить подробное логирование событий (`true`/`false`)                | `false`                 |

### Постоянный конфигурационный файл

Вы можете сохранять настройки, смонтировав директорию конфигурации:

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

### Запуск в фоновом режиме (Detached Mode)

Для длительных сессий на 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

# Просмотр логов
docker logs -f openhands
```

***

## Ускорение на GPU (интеграция локальной LLM)

Хотя сам OpenHands не использует GPU, сочетание его с **локальной LLM** работающим на GPU Clore.ai даёт вам мощного, экономичного автономного агента без API‑затрат.

### Вариант A: OpenHands + Ollama (рекомендуется для начинающих)

Сначала запустите Ollama, затем укажите OpenHands на него:

```bash
# 1. Запустите Ollama (см. руководство Ollama для полной информации)
docker run -d \
  --name ollama \
  --gpus all \
  -p 11434:11434 \
  -v ollama-data:/root/.ollama \
  ollama/ollama:latest

# 2. Загрузите модель, оптимизированную для кодирования
docker exec ollama ollama pull qwen2.5-coder:7b
# Или для большей мощности:
docker exec ollama ollama pull llama3.1:8b
docker exec ollama ollama pull deepseek-coder-v2:16b

# 3. Запустите OpenHands, указывая 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
```

> См. полный [руководство по Ollama](/guides/guides_v2-ru/yazykovye-modeli/ollama.md) для выбора модели, настройки производительности и конфигурации GPU.

### Вариант B: OpenHands + vLLM (высокая производительность)

Для максимальной пропускной способности с большими моделями:

```bash
# 1. Запустите vLLM с моделью для кодирования
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

# Дождитесь загрузки модели (~2–5 мин)
docker logs -f vllm | grep "Application startup"

# 2. Запустите OpenHands с бэкендом 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
```

> См.  [руководство по vLLM](/guides/guides_v2-ru/yazykovye-modeli/vllm.md) для полной настройки, опций квантизации и конфигураций с несколькими GPU.

### Рекомендуемые локальные модели для кодирования

| Модель                  | Размер | Мин. VRAM | Качество |
| ----------------------- | ------ | --------- | -------- |
| `qwen2.5-coder:7b`      | 7B     | 8 ГБ      | ★★★☆☆    |
| `deepseek-coder-v2:16b` | 16B    | 12 ГБ     | ★★★★☆    |
| `qwen2.5-coder:32b`     | 32B    | 24 ГБ     | ★★★★☆    |
| `llama3.1:70b`          | 70B    | 48 GB     | ★★★★★    |

***

## Подсказки и лучшие практики

### 1. Разумно используйте монтирование рабочего пространства

Смонтируйте вашу реальную директорию проекта как рабочее пространство, чтобы OpenHands мог напрямую редактировать ваши файлы:

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

### 2. Формулировка задачи для лучших результатов

OpenHands лучше всего работает со специфичными, выполнимыми подсказками:

```
✅ Хорошо: «Исправьте баг аутентификации в src/auth/login.py, где JWT‑токены 
         сразу истекают. Проблема в расчёте времени истечения токена.»

❌ Плохо: «Исправьте баг»
```

### 3. Мониторьте использование ресурсов

```bash
# Наблюдение за использованием GPU и памяти
watch -n 2 'nvidia-smi && docker stats --no-stream'
```

### 4. Установите лимиты итераций

Предотвращайте бесконтрольную работу агентов, потребляющих слишком много API‑токенов:

```bash
-e MAX_ITERATIONS=50  # Ограничение до 50 шагов на задачу
```

### 5. Интеграция с GitHub

OpenHands может решать проблемы на GitHub напрямую. Настройте в UI:

* GitHub Token: ваш персональный токен доступа с правами `repo` область
* OpenHands клонирует репозиторий, исправит проблему и создаст PR

### 6. Оценка стоимости

Для LLM на основе API оцените стоимость за задачу:

* Простое исправление бага: \~$0.05–0.15 (Claude Haiku/GPT-4o-mini)
* Сложная функция: \~$0.50–2.00 (Claude Sonnet/GPT-4o)
* При 100+ задач/день локальная LLM на Clore.ai окупает себя

***

## Устранение неполадок

### Доступ к Docker‑сокету запрещён (Permission Denied)

```bash
# Ошибка: отказано в доступе при попытке подключения к Docker-демону
# Исправление: убедитесь, что сокет доступен
ls -la /var/run/docker.sock
# Должно показывать: srw-rw---- 1 root docker ...

# При необходимости добавьте вашего пользователя в группу docker
usermod -aG docker $USER
# Затем перезапустите оболочку или используйте: newgrp docker
```

### Сандбокс‑контейнер не запускается

```bash
# Проверьте, доступен ли runtime‑образ
docker pull ghcr.io/all-hands-ai/runtime:0.38-nikolaik

# Проверьте лимиты GHCR (возможно потребуется аутентификация)
docker login ghcr.io
```

### Порт 3000 недоступен

```bash
# Убедитесь, что контейнер запущен и порт привязан
docker ps | grep openhands
docker port openhands

# Проверьте брандмауэр Clore.ai — убедитесь, что порт 3000 включён в маппинг портов
# В панели Clore.ai: Server → Ports → Add 3000:3000
```

### Ошибки подключения LLM с Ollama

```bash
# Проверьте, доступен ли Ollama из контейнера OpenHands
docker exec openhands curl http://host.docker.internal:11434/api/tags

# Если не удаётся, проверьте, был ли включён флаг --add-host в docker run
# Также проверьте, что контейнер Ollama запущен:
docker ps | grep ollama
docker logs ollama | tail -20
```

### Агентные петли выполняются бесконечно

```bash
# Уменьшите макс. итерации
docker stop openhands
docker run ... -e MAX_ITERATIONS=30 ...

# Или установите таймаут
-e SANDBOX_TIMEOUT=60
```

### Недостаточно памяти (OOM)

```bash
# Проверить использование памяти
free -h
docker stats

# Если запускаете локальную LLM, попробуйте меньшую модель
docker exec ollama ollama pull qwen2.5-coder:3b

# Или используйте квантизированную версию (меньше VRAM)
docker exec ollama ollama pull llama3.1:8b-instruct-q4_K_M
```

***

## Дополнительное чтение

* [Репозиторий OpenHands на GitHub](https://github.com/All-Hands-AI/OpenHands) — Исходный код, issues и релизы
* [Документация OpenHands](https://docs.all-hands.dev) — Официальная документация, включая настройку LLM
* [Ollama на Clore.ai](/guides/guides_v2-ru/yazykovye-modeli/ollama.md) — Запускайте локальные LLM для бесплатного вывода агентов
* [vLLM на Clore.ai](/guides/guides_v2-ru/yazykovye-modeli/vllm.md) — Высокопроизводительная локальная подача LLM
* [Руководство по сравнению GPU](/guides/guides_v2-ru/nachalo-raboty/gpu-comparison.md) — Выберите подходящий GPU для вашей нагрузки
* [Discord OpenHands](https://discord.gg/ESHStjSjD4) — Поддержка сообщества и рекомендации по моделям
* [Таблица лидеров SWE-bench](https://www.swebench.com) — Сравнивайте производительность агентов на реальных GitHub‑issue


---

# 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-ru/ai-platformy-i-agenty/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.