OpenHands: подключение своей модели через API-шлюз

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

Модель под ним не зашита: подойдёт любой совместимый API.

Настройка провайдера

OpenHands обращается к моделям через LiteLLM, поэтому важны три вещи: базовый адрес, ключ и имя модели с префиксом провайдера. Для шлюза проще всего OpenAI-совместимый вариант: префикс openai/ перед именем модели и адрес с /v1.

Через переменные окружения:

export LLM_MODEL=openai/gpt-5.6-sol
export LLM_BASE_URL=https://api.zukko.pro/v1
export LLM_API_KEY=fetch_ваш_ключ

Или в интерфейсе: Settings → вкладка LLM → включите Advanced options и задайте Custom Model openai/gpt-5.6-sol, Base URL https://api.zukko.pro/v1 и API Key — тогда переменные не нужны.

Через тот же адрес можно звать и Claude — например, openai/claude-opus-5-5: шлюз сам переведёт запрос в нужный формат.

Обратите внимание на /v1 в адресе и на префикс openai/ в имени модели: без /v1 запросы уходят мимо и получают 404, а без префикса LiteLLM не поймёт, каким протоколом ходить. Это самые частые ошибки при подключении.

Ключ вида fetch_... берётся в кабинете Zukko↗ и работает в обоих форматах.

Выбор модели

Список того, что доступно прямо сейчас:

curl https://api.zukko.pro/v1/models -H "Authorization: Bearer fetch_ваш_ключ"

Модели, не отвечающие на проверку в этот момент, из списка убираются — специально ради агентов, чтобы вы не выбрали сломанную наугад.

Для OpenHands существенно, чтобы модель уверенно вызывала инструменты: агент работает длинными цепочками, и модель, которая путается в вызовах, сожжёт бюджет на повторах. Основной вариант — claude-opus-5-5 или gpt-5.6-sol ($0.30/$0.30 за миллион), glm-5.3 заметно дешевле ($0.10/$0.10, контекст 128K) и может подойти для задач попроще — проверьте на своих задачах.

Про песочницу и расход

Изоляция даёт безопасность, но у неё есть побочный эффект для кошелька: агент в контейнере чаще исследует окружение заново — ставит зависимости, смотрит структуру, проверяет версии. Каждое такое действие уезжает в контекст и оплачивается на всех последующих шагах.

Два способа это сдержать. Первый — давать задачу конкретнее: не «разберись с проектом», а «в файле app/models.py поправь тип поля days». Второй — не тянуть одну сессию через несколько разных задач: закончили — начинайте новую.

Подробный разбор того, откуда берётся расход в агентном цикле, — в статье про стоимость агентной сессии→.

Если не заработало

401. Ключ не подставился или обрезан при копировании. Проверьте пробел в конце.

404. Нет /v1 в Base URL или префикса openai/ в имени модели.

Агент предлагает написать код руками. Вызовы инструментов не доходят. Проверяется отдельным запросом — см. разбор этой ошибки→.

Долгое молчание на первом шаге. Часть моделей тратит токены на внутреннее рассуждение перед ответом; при маленьком лимите вывода до текста дело не доходит. Поднимите лимит до нескольких тысяч токенов.