# OpenHands: настройка автономного coding-агента через RouterAI (Claude, DeepSeek, GLM)

## OpenHands

OpenHands — открытый автономный агент для разработки. Он читает код проекта, правит файлы, запускает команды в терминале, ставит зависимости и гоняет тесты, пока задача не будет решена. Команды выполняются в изолированной песочнице (Docker-контейнер) или напрямую на машине — это зависит от способа запуска. Подробнее о том, чем агент отличается от обычного чат-бота, — в статье [Автономный ИИ-агент](/pages/avtonomnyy-ii-agent).

Работать с OpenHands можно тремя способами:

- **CLI** — команда `openhands` в терминале; headless-режим (`openhands --headless`) подходит для скриптов и CI;
- **веб-интерфейс** — Agent Canvas (`agent-canvas`, адрес `http://localhost:8000`) или полноценный GUI через `openhands serve`;
- **облако** — OpenHands Cloud, к RouterAI это не относится.

OpenHands обращается к моделям через LiteLLM, поэтому подключается к любому OpenAI-совместимому провайдеру. RouterAI даёт единый ключ и каталог из сотен моделей, работает из России без VPN, оплата в рублях. Агента можно запускать на Claude Sonnet 5.5 для сложных задач и переключаться на дешёвые модели для рутины.

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

- macOS, Linux или Windows через WSL (нативный Windows для CLI официально не поддерживается)
- для CLI: Python 3.12 и [uv](https://docs.astral.sh/uv/)
- для Agent Canvas через npm: Node.js 24+ и `uv`; для Docker-варианта: запущенный Docker
- API-ключ RouterAI из [личного кабинета](/settings/keys)

> OpenHands выполняет команды и меняет файлы без вашего участия. Запускайте его в Docker-песочнице или на отдельной машине и не давайте доступ к каталогам с чужими данными.

## Установка

Актуальные версии на момент написания: OpenHands CLI 1.16.0 (PyPI), Agent Canvas 1.30.0 (GitHub).

### CLI

```bash
uv tool install openhands --python 3.12
openhands
```

Обновление: `uv tool upgrade openhands --python 3.12`. Есть и установочный скрипт с готовым бинарником: `curl -fsSL https://install.openhands.dev/install.sh | sh`.

### Веб-интерфейс: Agent Canvas

Через npm (агент работает прямо на вашей машине):

```bash
npm install -g @openhands/agent-canvas
agent-canvas
```

Через Docker (агент видит только смонтированный каталог проектов):

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

Интерфейс откроется на `http://localhost:8000` (для Docker-образа — `http://localhost:8000/canvas`). Другой вариант веб-интерфейса — `openhands serve`: он поднимает GUI в Docker на `http://localhost:3000`.

При первом открытии Agent Canvas запускает мастер настройки: добавление бэкенда (`Add a backend`, по умолчанию `Local`), выбор агента (`OpenHands`) и шаг `Set up your LLM`. Если на первом шаге мастер просит `API Key`, это ключ бэкенда `LOCAL_BACKEND_API_KEY`, а не ключ RouterAI: при автогенерации его можно найти в логах контейнера или в файле `/home/openhands/.openhands/agent-canvas/api-key.txt` внутри него. Модель можно настроить прямо в мастере (на вкладке `Advanced` те же поля, что и ниже) либо пропустить шаг (`Skip for now`) и вернуться к нему в `Settings > LLM`.

![Стартовая страница Agent Canvas после первого запуска: бэкенд Local подключён](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/44b40323908d7f5f86c0367c025c081f.png)

## Подключение к RouterAI

OpenHands читает настройки LLM из трёх переменных. Они описаны в справочнике CLI и в разделе Configuration Options документации:

| Переменная | Значение для RouterAI |
| --- | --- |
| `LLM_BASE_URL` | `https://routerai.ru/api/v1` |
| `LLM_API_KEY` | ваш ключ RouterAI (`sk-xxxxxxxxxxxxxxxx`) |
| `LLM_MODEL` | `openai/anthropic/claude-sonnet-5.5` |

Обратите внимание на префикс `openai/` перед id модели. LiteLLM использует его, чтобы понять, что запросы идут в OpenAI-совместимый API по указанному Base URL. Дальше идёт обычный id из [каталога RouterAI](/models): `anthropic/claude-sonnet-5.5`.

### CLI

Передайте переменные окружения и добавьте флаг `--override-with-envs`: без него CLI берёт сохранённые настройки из `~/.openhands/settings.json`.

```bash
export LLM_BASE_URL="https://routerai.ru/api/v1"
export LLM_API_KEY="sk-xxxxxxxxxxxxxxxx"
export LLM_MODEL="openai/anthropic/claude-sonnet-5.5"

openhands --override-with-envs
```

Так же настройки можно задать при первом запуске: CLI сам предложит выбрать провайдера и ввести ключ, а результат сохранит в `~/.openhands/settings.json`.

После запуска CLI показывает версию и приглашение ввести задачу; сообщение `All set up!` значит, что настройки приняты.

![Запуск openhands --override-with-envs: версия OpenHands CLI v1.16.0, сообщение All set up! и поле ввода задачи](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/0df6234797759379b571ebed2969974a.png)

### Веб-интерфейс

Откройте `Settings > LLM` (значок шестерёнки внизу слева) и нажмите `Add LLM Profile`. На открывшейся странице:

1. Введите имя профиля в поле `Profile Name`, например `routerai-sonnet`.
2. Переключитесь на вкладку `Advanced` — здесь можно задать собственную модель и Base URL.
3. В поле `Custom Model` введите `openai/anthropic/claude-sonnet-5.5`.
4. В поле `Base URL` введите `https://routerai.ru/api/v1`.
5. В поле `API Key` вставьте ключ RouterAI.
6. Нажмите `Save`. Перед сохранением настройки проверяются на бэкенде: при неверном ключе или модели профиль не сохранится и покажет ошибку.

![Страница Add LLM Profile, вкладка Advanced: Profile Name, Custom Model, Base URL RouterAI и API Key](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/6cff0706097d85bfdd534d2b8ad4db20.png)

Профиль появится в списке `Available Profiles`; профиль по умолчанию помечен значком `Default`, сменить его можно в меню профиля (`Set as default`). Если ключ и Base URL понадобятся для нескольких моделей, создайте в `Settings > LLM` блок `Provider connections` → `Add connection` и привяжите его к профилям — ключ придётся менять в одном месте.

Base URL должен быть доступен **бэкенду** OpenHands, а не только браузеру. С `https://routerai.ru/api/v1` это не проблема, но для локальных серверов в Docker нужен `host.docker.internal`.

## Выбор модели

Агенту нужны модели с вызовом инструментов (tool calling) и длинным контекстом. Все модели ниже поддерживают `tools` по данным каталога. Цены смотрите в [каталоге](/models) — они зависят от модели и меняются.

| Модель (id в RouterAI) | Для чего |
| --- | --- |
| `anthropic/claude-sonnet-5.5` | основная модель для кода: фичи, исправление багов, рефакторинг |
| `anthropic/claude-opus-5.5` | сложные многошаговые задачи в больших кодовых базах, код-ревью |
| `anthropic/claude-haiku-5.5` | быстрые и недорогие прогоны, мелкие правки |
| `deepseek/deepseek-v4-flash` | дешёвые массовые прогоны, контекст около 1 млн токенов |
| `z-ai/glm-5.3` | альтернатива для инженерных задач; режим рассуждений включён всегда |

В OpenHands перед каждым id добавляйте `openai/`: например, `openai/deepseek/deepseek-v4-flash`.

Профили LLM позволяют держать несколько моделей под рукой и переключаться посреди разговора. Создайте профили в `Settings > LLM` и в чате отправьте `/model` — список профилей, `/model <имя-профиля>` — переключение. Типичная схема: план с сильной моделью, реализация на дешёвой. Контекст разговора при переключении сохраняется.

![Раздел Available Profiles в Settings > LLM с двумя профилями: claude-sonnet-5.5 (Default) и deepseek-v4-flash](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/552270ca87361048ee33eeb0da49aa28.png)

## Запуск задачи

### В CLI

```bash
openhands --override-with-envs -t "Исправь падающий тест в tests/test_auth.py"
```

Флаг `-t` задаёт начальную задачу, `-f task.txt` берёт её из файла. По умолчанию агент спрашивает подтверждение перед действиями. `--always-approve` отключает вопросы, `--llm-approve` включает проверку действий отдельной моделью. `Esc` ставит агента на паузу, `Ctrl+P` открывает палитру команд с настройками, `Ctrl+Q` — выход.

Для скриптов и CI есть headless-режим. Он всегда работает без подтверждений, поэтому запускайте его только в изолированной среде:

```bash
openhands --headless --override-with-envs -t 'Создай hello.py, который печатает Hello, RouterAI!, и запусти его'
```

Задачу с `!` берите в одинарные кавычки: в двойных интерактивный bash раскроет `!` как историю команд и ответит `event not found`. Добавьте `--json`, чтобы получить события агента построчно в формате JSONL.

![Интерактивный CLI OpenHands: агент создал hello.py через file_editor и запустил его командой в terminal](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/751f5bfc851960f351612ffebf174379.png)

### В веб-интерфейсе

1. Откройте `http://localhost:8000` (для Docker-образа — `http://localhost:8000/canvas`) и нажмите `New Chat`.
2. Нажмите `Open Workspace` и выберите папку проекта. Для Docker это каталог внутри `/projects`: `+ Add Workspace` → `Add this directory` → `Confirm`.
3. Убедитесь, что в селекторе рядом с полем ввода выбран профиль с моделью RouterAI (например, `claude-sonnet-5.5`).
4. Опишите задачу в поле ввода, нажмите `Enter` и следите за действиями агента в ленте.

![Agent Canvas: агент на claude-sonnet-5.5 добавил в демо-проект команду search и запустил её](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/5ad0395a70fa783c63e8bf265ec47591.png)

## Расход токенов

Агент делает десятки запросов за одну задачу и каждый раз отправляет накопленную историю, поэтому длинные сессии стоят заметно дороже коротких. Что реально влияет на расход:

- **Сжатие истории.** В `Settings > Agent` в профиле агента есть раздел `Condenser`: переключатель `Enable Memory Condensation` включает сжатие контекста, а параметр `Memory condenser max history size` задаёт, после скольких событий старая история заменяется кратким пересказом. В документации прямо указано, что это снижает задержку и расход токенов.
- **Модель под задачу.** Планирование — на Sonnet 5.5, рутина — на `deepseek/deepseek-v4-flash` или Haiku 5.5, переключение через `/model`.
- **Модель для заголовков.** В `Settings > Application` параметр `Conversation titles` позволяет выбрать дешёвый профиль для генерации названий разговоров, чтобы не тратить на это основную модель.
- **Короткие разговоры.** Новая тема — новый разговор: история не тянется за агентом. Продолжить прошлый разговор можно через `openhands --resume`.
- **Контроль.** Следите за расходом в [личном кабинете RouterAI](/settings/billing) и ставьте паузу (`Esc`), если агент зациклился.

## Проверка подключения

Сначала проверьте, что RouterAI отвечает для выбранной модели (в запросе — id без префикса `openai/`):

```bash
curl https://routerai.ru/api/v1/chat/completions \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "Ответь одним словом: ок"}]
  }'
```

Затем запустите короткую задачу в headless-режиме (пример выше). В выводе должна появиться строка вида `Agent initialized with model: openai/anthropic/claude-sonnet-5.5`, а в каталоге появится созданный `hello.py`. В веб-интерфейсе отправьте короткое сообщение в новом разговоре: если модель отвечает, подключение работает.

## Решение проблем

### Ошибка `LLM Provider NOT provided`

В `LLM_MODEL` или поле `Custom Model` не хватает префикса провайдера. Используйте `openai/anthropic/claude-sonnet-5.5`, а не просто `anthropic/claude-sonnet-5.5`, и проверьте, что указан Base URL.

### Агент не видит модель или отвечает ошибкой авторизации

- Сверьте id модели с [каталогом](/models) — опечатка в id даёт ошибку `model not found`.
- Проверьте ключ в `LLM_API_KEY` или поле `API Key`; при ошибке 401 обновите ключ и сохраните профиль заново.
- В CLI добавьте `--override-with-envs`, иначе переменные игнорируются в пользу `~/.openhands/settings.json`.
- Ошибка 402 означает, что на балансе недостаточно средств: пополните его в разделе [Биллинг](/settings/billing).
- Новые настройки действуют на новые разговоры: старый разговор перезапустите.

### Агент ведёт себя как чат-бот и не запускает команды

Обычно модель не справляется с вызовом инструментов или у неё слишком маленький контекст. Выберите модель посильнее (Sonnet 5.5, Opus 5.5) и убедитесь, что для неё доступен `tools` в [каталоге](/models).

### Docker не стартует или контейнер перезапускается

- `docker ps` должен работать — запустите Docker Desktop или Docker Engine.
- Причину падения контейнера покажет `docker logs <имя-контейнера>`.
- Если порт 8000 занят, пробросьте другой: `-p 127.0.0.1:8080:8000`.
- На Linux каталог `~/.openhands` с хоста может вызвать `unable to open database file` из-за прав доступа: используйте именованный том `openhands-data`, как в команде выше.

### Долгие ответы и таймауты

Модели с рассуждением (Sonnet 5.5, GLM 5.3) отвечают медленнее, чем быстрые. Для рутинных прогонов используйте Haiku 5.5 или DeepSeek V4 Flash, а при зависании поставьте агента на паузу (`Esc`) и уточните задачу.

## Что дальше

- [Каталог моделей](/models) — подберите модель под задачу и бюджет
- [Автономный ИИ-агент](/pages/avtonomnyy-ii-agent) — как устроены такие агенты
- [Вайб-кодинг в Claude Code через RouterAI](/pages/vibe-coding-claude-code) — ещё один CLI-агент
- [Hermes Agent через RouterAI](/pages/hermes-agent-routerai) — универсальный агент с Telegram-ботом
- [Аутентификация](/docs/guides/overview/authentication) — управление API-ключами и безопасность