От Qwen Code нужны ровно две вещи: базовый адрес
https://speshu.ai/api/v1 и API-ключ. Агент говорит с /api/v1/chat/completions обычным OpenAI-совместимым запросом, поэтому код менять не нужно — указываете адрес, вставляете ключ и выбираете модель. Ключ создаётся в личном кабинете, подробности — в разделе Аутентификация.Требования
- Node.js 20 или новее
- macOS, Linux или Windows
- Ключ SpeShu.AI
Установка
qwen и переменные окружения вступили в силу.
1
Сохраните ключ в переменной окружения
~/.zshrc или ~/.bashrc, чтобы ключ переживал новый терминал. Проверка, которая ничего не стоит:cURL
{"RUB": "1250.00", "USD": "3.75"} означает, что ключ принят. Пустой объект {} — тоже корректный ответ: ключ рабочий, записей в кошельке пока нет.2
Возьмите идентификатор модели из каталога
Идентификаторы текстовых моделей не зашивайте в код: состав каталога меняется, и зашитый в конфиг идентификатор начинает падать с
404 model_not_found. Возьмите его из GET /api/v1/models и сохраните рядом с ключом:cURL
.data[0] — первый элемент, чтобы пример был запускаемым. Выбирайте модель по cost_completion, context_length и наличию зрения. Формат ответа разобран в разделе Модели и цены.3
Укажите адрес шлюза и ключ в настройках агента
Собственная конфигурация Qwen Code — файл Диалоги
settings.json. Разделы Model Providers и Model в нём отвечают за то, куда агент ходит и какой моделью говорит; ключ при этом лучше оставить в переменной окружения, а в файле сослаться на её имя./auth и /model — самый устойчивый путь: они есть во всех линейках и не зависят от того, как именно устроен файл конфигурации в вашей версии.4
Запустите первый сеанс и проверьте, что всё работает
Конфигурация
Переменные окружения
Самый короткий способ подключения — экспортировать обе переменные и назвать их в том виде, который агент читает по умолчанию:OPENAI_BASE_URL здесь — не про провайдера OpenAI. Это штатная переменная, которую Qwen Code читает для любого OpenAI-совместимого адреса.
Файл настроек
Если хотите зафиксировать адрес и ключ в конфигурации, откройтеsettings.json агента и добавьте провайдера. Местоположение:
Форма раздела зависит от версии: у ранних выпусков
modelProviders — объект, ключ которого — имя провайдера, у поздних — список записей с явными полями. Оба варианта описывают одно и то же: адрес шлюза, имя переменной с ключом и список моделей.
envKey — имя переменной окружения, а не сам ключ. Так секрет не попадает в файл на диске.
Проверить, какой вариант читает ваша версия, можно так: запустите
qwen из временного каталога без файла .qwen/settings.json в проекте, выполните /model и посмотрите, подхватились ли адрес и ключ из переменных окружения. Если подхватились — файл можно не трогать вообще.Что ещё работает
Потоковая передача
Отдельного флага для неё не нужно: агент всегда читает ответ по частям, иначе интерфейс замирал бы на минуты. Формат кадров, маркер[DONE] и кадр с usage.cost.total_cost разобраны в гайде Потоковая передача.
Инструменты агента
Встроенные инструменты (чтение файлов, правка, запуск команд) работают поверх обычногоtools из протокола вызова функций. Полный цикл вызова — на странице Вызов функций.
MCP-серверы
Qwen Code умеет подключать внешние инструменты через MCP; конфигурация лежит в файле.mcp.json в корне проекта. Сами MCP-серверы ходят в сторонние сервисы и от SpeShu.AI ничего не требуют. Разбор подключения — в гайде MCP.
Изображения и файлы во входе
Скриншот, сохранённый в проект, агент передаёт модели как изображение — так работает зрение. Не каждая модель его принимает: запрос с картинкой к модели без зрения отвергается целиком с400 invalid_request. Требования к ссылке и все четыре типа блоков контента — в гайде Медиаввод.
Генерация медиа
Медиа API не OpenAI-совместимый, и агент его не вызывает. Задачи создаются отдельным запросом кPOST /api/v1/async/media/tasks с оплатой при создании и последующим опросом статуса — формат конверта и Idempotency-Key в разделе Создать задачу. Идентификаторы медиа-моделей, в отличие от текстовых, стабильны: берите их из GET /api/v1/media/models.
Об эмбеддингах
Частые проблемы
404 на любом запросе, хотя ключ и модель верны
404 на любом запросе, хотя ключ и модель верны
Проверьте адрес целиком:
https://speshu.ai/api/v1, без завершающего слэша и без потерянного /v1. Диагностика: echo $OPENAI_BASE_URL. Разбор адресов — в Введении в API.401 invalid_api_key при верном ключе в окружении
401 invalid_api_key при верном ключе в окружении
Агент читает
OPENAI_API_KEY, а не SPESHU_API_KEY. Либо переименуйте переменную, либо укажите в настройках envKey с именем вашей переменной. Проверьте значение отдельно: curl -s https://speshu.ai/api/v1/balance -H "Authorization: Bearer $SPESHU_API_KEY".404 model_not_found после обновления каталога
404 model_not_found после обновления каталога
В конфигурации или в выборе модели зашит идентификатор, которого больше нет в
GET /api/v1/models. Обновите переменную и выберите модель заново через /model. Почему так — в разделе Модели и цены.400 invalid_request на запросе, который агент отправляет сам
400 invalid_request на запросе, который агент отправляет сам
Агент подставляет параметры генерации, которых в API нет, — например, настройки рассуждения или температуры из своей секции настроек. Снимите их в настройках агента и повторите: незнакомые поля отвергаются целиком. Полная таблица кодов — на странице Ошибки.
402 insufficient_quota при первом же сеансе
402 insufficient_quota при первом же сеансе
На балансе нет положительной суммы. Проверка идёт до обращения к модели, деньги за отказ не списываются. Пополнение — на speshu.ai/profile, таймауты и квоты — в разделе Лимиты.
Всё остальное
Всё остальное
Форматы ошибок, коды и цикл повторов — на странице Ошибки.
Что дальше
Начало работы
Полный маршрут от ключа до медиа-задачи
Модели и цены
Как выбрать идентификатор и на что смотреть
Потоковая передача
SSE,
[DONE] и кадр со списаниемВызов функций
Полный цикл вызова инструмента