support@routerai.ru

Загрузка...

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

Содержание статьи

OpenHands

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

Работать с 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
  • для Agent Canvas через npm: Node.js 24+ и uv; для Docker-варианта: запущенный Docker
  • API-ключ RouterAI из личного кабинета

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

Установка

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

CLI

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 (агент работает прямо на вашей машине):

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

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

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 подключён

Подключение к 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: anthropic/claude-sonnet-5.5.

CLI

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

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! и поле ввода задачи

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

Откройте 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

Профиль появится в списке 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 по данным каталога. Цены смотрите в каталоге — они зависят от модели и меняются.

Модель (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

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

В CLI

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

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

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

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

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

Интерактивный CLI OpenHands: агент создал hello.py через file_editor и запустил его командой в terminal

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

  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 и запустил её

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

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

  • Сжатие истории. В 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 и ставьте паузу (Esc), если агент зациклился.

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

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

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 модели с каталогом — опечатка в id даёт ошибку model not found.
  • Проверьте ключ в LLM_API_KEY или поле API Key; при ошибке 401 обновите ключ и сохраните профиль заново.
  • В CLI добавьте --override-with-envs, иначе переменные игнорируются в пользу ~/.openhands/settings.json.
  • Ошибка 402 означает, что на балансе недостаточно средств: пополните его в разделе Биллинг.
  • Новые настройки действуют на новые разговоры: старый разговор перезапустите.

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

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

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) и уточните задачу.

Что дальше