OpenHands + JoinGonka Gateway: агент на своём endpoint

У проекта сегодня несколько интерфейсов, и от того, какой из них запущен у вас, зависит, где искать настройки модели. Сами значения везде одни и те же — отличается только путь к ним.

Для Agent Canvas нужны Node.js и uv — на нём работает локальный сервер агента (подробности — в инструкции по установке). Инструкция называет Node.js 22.12 или новее, но сам пакет начиная с версии 1.17 объявляет Node.js 24 и новее — ставьте 24, чтобы не получить предупреждение о несовместимой версии. Есть и вариант в контейнере: образ ghcr.io/openhands/agent-canvas отдаёт интерфейс на http://localhost:8000/canvas и видит только те каталоги, которые вы смонтировали.

Ключ JoinGonka. Зарегистрируйтесь на gate.joingonka.ai/register, подтвердите адрес и создайте ключ с префиксом jg- в разделе «API-ключи». Один ключ и один баланс действуют для всех моделей сети. В списке инструментов установщика @joingonka/setup OpenHands нет, и это не упущение: его настройки живут в интерфейсе и в защищённом хранилище бэкенда, а не в текстовом конфиге, который можно аккуратно дописать снаружи.

Шаг 1. Запустите Agent Canvas и откройте Settings > LLM. Мастер первого запуска предлагает собственного провайдера OpenHands — этот шаг можно пропустить, к настройкам легко вернуться позже.

Шаг 2. Нажмите Add LLM Profile и перейдите на вкладку Advanced: вкладка Basic предлагает только провайдеров и модели из встроенного списка.

Шаг 3. Заполните три поля:

Шаг 4. Сохраните профиль. Перед сохранением Canvas проверяет конфигурацию запросом с бэкенда: если ключ отклонён или модель недоступна, профиль не сохранится, а вы увидите текст ошибки.

Шаг 5. Начните новый разговор и отправьте короткое сообщение. Уже открытые разговоры продолжают работать на той модели, с которой начались.

Почему openai/. LiteLLM определяет провайдера по префиксу модели. Префикс openai/ означает не «модель от OpenAI», а «говорить с сервером по протоколу OpenAI Chat Completions». Срезается только первый сегмент, так что до шлюза доходит настоящий идентификатор — deepseek-ai/DeepSeek-V4-Flash-0731. В документации OpenHands та же схема показана на примере openai/qwen/qwen3.6-35b-a3b. Без префикса LiteLLM откажется работать с сообщением LLM Provider NOT provided.

Почему /v1 и ничего больше. LiteLLM ходит к серверу через официальный клиент OpenAI, а тот сам дописывает /chat/completions. Поэтому адрес обязан заканчиваться на /v1: без суффикса запрос уйдёт мимо API, с лишним хвостом — на путь, которого не существует. И ещё одно требование Canvas: адрес должен быть доступен с бэкенда, а не только из браузера. Шлюз — публичный HTTPS-адрес, из контейнера Docker он виден так же, как с хоста; приёмы вроде host.docker.internal нужны только для моделей на вашей машине.

Профили под все три модели. Заведите по профилю на каждую модель сети и назовите их коротко — например deepseek, glm и minimax (документация говорит о лимите в десять профилей). Переключаться можно прямо в разговоре, не теряя контекста: кнопкой выбора профиля в поле ввода или командой /model glm; /model без аргумента покажет список. Чтобы не вставлять ключ в каждый профиль, его можно сохранить один раз в блоке Provider Connections — он доступен на локальном бэкенде.

Прежний интерфейс в Docker. Поля те же: Settings → вкладка LLM → включить Advanced → Custom Model, Base URL, API Key → Save Changes.

CLI ставится одной командой через uv и при первом запуске сам проведёт через настройку модели; позже к ней возвращает Ctrl+P → Settings:

uv tool install openhands --python 3.12
openhands

Для скриптов удобнее переменные окружения. Важная деталь: по умолчанию CLI их игнорирует и применяет только с флагом --override-with-envs — на один запуск, ничего не сохраняя:

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

Тот же набор работает без интерфейса — для CI и пакетных задач:

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

В headless-режиме агент всегда действует с автоодобрением, поэтому запускайте его там, где ему можно всё: в отдельном каталоге или контейнере. Флаг --json превращает вывод в поток событий JSONL — его удобно разбирать в конвейере. Именно так мы проверяли связку 21 сентября 2026 на CLI 1.16.0: в шапке CLI печатает Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731, затем агент читает файл и отвечает по существу.

Сохранённые настройки CLI лежат в ~/.openhands/agent_settings.json: модель в нём меняется правкой трёх полей блока llm — model, api_key и base_url. Создавать файл с нуля не стоит: мастер первого запуска пишет туда и остальные настройки агента, в том числе сжатие истории, без которого долгий разговор упрётся в окно контекста.

Если вы встраиваете агента в собственный код, те же три значения принимает OpenHands SDK:

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

Цена у моделей сети одна, поэтому выбор — про поведение. Автономному агенту важны две цифры. Окно контекста: каждый шаг заново отправляет историю, и чем окно длиннее, тем дольше агент работает без потерь. Потолок ответа: шаг, на котором агент пишет большой файл целиком, должен уместиться в один ответ. В таблице — результаты нашего прогона одной и той же задачи (прочитать файл и найти ошибку) через OpenHands CLI 1.16.0 с SDK 1.21.0.

Рабочая схема для долгой задачи повторяет совет из документации OpenHands — планировать одной моделью, исполнять другой. Начните разговор на профиле glm и попросите план без правок файлов; затем отправьте /model deepseek и дайте команду исполнять. История, файлы и состояние задачи при переключении сохраняются. Профиль minimax держите третьим: на него удобно уйти, когда у двух других в час пик закончилась ёмкость, и ему же в Settings > Application можно отдать генерацию заголовков разговоров.

Сжатие истории. Даже окно в сотни тысяч токенов на многочасовой задаче конечно. В OpenHands за это отвечает конденсер: он сворачивает старые события в краткое резюме, что, по словам документации, снижает задержку и расход токенов в долгих разговорах. В Agent Canvas он настраивается в разделе Settings > Condenser; в нашем прогоне CLI включил его сам, с порогом в 80 событий.

Лимиты модели. Окно контекста и потолок ответа OpenHands берёт из справочника LiteLLM, а идентификаторов сети Gonka в нём нет (мы проверили на LiteLLM 1.81), так что своих значений для этих моделей у агента нет. Работе это не мешает: потолок ответа шлюз применяет сам, по таблице выше. Захотите задать лимиты явно — в SDK это поля max_input_tokens и max_output_tokens, а в Canvas полный набор полей профиля открывает вкладка All. Подробности о модели по умолчанию — в обзоре DeepSeek V4 Flash.

Убедиться, что запросы действительно идут через шлюз, можно с двух сторон. Со стороны OpenHands — новый разговор и короткое задание вроде «прочитай README и перескажи одной фразой»: агент должен вызвать инструмент и ответить. Со стороны шлюза — кабинет, раздел «Использование»: запрос появится в разбивке «По моделям», а в блоке «По ключам» обновится время последнего запроса. Пусто — значит, разговор идёт на другом профиле: проверьте, какой из них отмечен активным.

По документации OpenHands число повторов и паузы между ними при 429 настраиваются переменными LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT и LLM_RETRY_MAX_WAIT. Значения по умолчанию в документации и в SDK расходятся, поэтому ориентируйтесь на фактические: в состоянии разговора CLI 1.16.0 мы видели 5 попыток с паузами от 8 до 64 секунд.

Через JoinGonka Gateway токены стоят $0.0069 за миллион на входе и $0.021 за миллион на выходе — цена одинакова для всех моделей сети и подставляется на этой странице из живого источника.

Оценки в правой колонке — по ценам на сентябрь 2026; как устроена экономика агентов, подробно разобрано в статье про самый дешёвый API для AI-агентов.

Потолок расхода. OpenHands советует ставить лимиты трат — у шлюза он встроен в саму модель оплаты: баланс предоплаченный, и больше, чем на счёте, агент не потратит. Остаток и расход по дням видны в кабинете. Для CI и фоновых автоматизаций заведите отдельный ключ, чтобы их расход не смешивался с вашим; дочерние ключи с дневным лимитом описаны в статье про Management Keys.

Граница доверия. Agent Canvas, запущенный через npm, работает с правами вашего пользователя и видит всю файловую систему. Для чужого кода берите вариант в Docker: агент увидит только смонтированный каталог. Это свойство самого OpenHands, от провайдера модели оно не зависит.

Переписка остаётся у вас. Историю разговора OpenHands хранит у себя, в ~/.openhands, и отправляет её модели с каждым шагом; шлюз переписку не хранит — ваши промпты и код не остаются на нём после ответа.

Если в задаче есть картинки — скриншоты интерфейса, схемы — заведите для неё отдельный профиль с vision-моделью: модели сети Gonka текстовые. Для кода, команд и файлов это не ограничение.