OpenCode + NeuroAPI: провайдер openai-compatible

OpenCode — терминальный AI-агент, который подключается к провайдерам через AI SDK. Для NeuroAPI используется OpenAI-совместимый сценарий: тот же протокол, что и у OpenAI SDK, но с другим baseURL и ключом. Сначала создайте ключ NeuroAPI в кабинете и выберите тариф; затем выпишите точные ID моделей из /price или GET /v1/models.

Установите OpenCode по официальной инструкции и убедитесь, что команда opencode доступна в терминале. Дальше понадобится файл конфигурации opencode.json в каталоге проекта: в нём описывается провайдер, адрес API и список моделей.

• Ключ NeuroAPI — отдельный под OpenCode.
• ID моделей — точные, из /price или GET /v1/models.
• Конфигурация — в opencode.json проекта.
• Проверьте версию OpenCode: набор полей может отличаться.

В документации OpenCode кастомный провайдер описывается в секции provider. Для OpenAI-совместимого API указывается npm: @ai-sdk/openai-compatible, произвольный уникальный ID провайдера, отображаемое имя name и объект options с baseURL и apiKey. Для NeuroAPI baseURL равен https://neuroapi.host/v1.

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

• provider: уникальный ID, например neuroapi.
• npm: @ai-sdk/openai-compatible.
• options.baseURL: https://neuroapi.host/v1.
• options.apiKey: ключ или ссылка на переменную окружения.
• options.headers — при необходимости дополнительные заголовки.

Модели описываются в объекте models как отображение ID модели на её настройки. Документация OpenCode подчёркивает: каждый ID должен совпадать с тем, что возвращает GET /v1/models. Если ID отличается хотя бы регистром или суффиксом версии, модель не появится в выборе или запрос вернёт 404.

Для кастомного провайдера OpenCode не получает сведения о контексте из внешнего каталога, поэтому полезно указать limit.context и limit.output вручную — по данным карточки модели в /price. Это помогает агенту корректнее планировать длину контекста и не отправлять заведомо слишком большой запрос.

• Ключ в models — точный ID модели.
• limit.context — максимальный входной контекст.
• limit.output — максимальный объём ответа.
• Значения берите из карточки модели, не из памяти.

После сохранения конфигурации запустите OpenCode и проверьте, что провайдер и модели видны в списке. Отправьте короткую задачу — это проверит ключ, baseURL и выбранный ID. Если провайдер виден, но моделей нет, проверьте формат models и совпадение ID с ответом GET /v1/models.

Ошибка 401 означает неверный ключ, 404 — опечатку в ID модели или адресе, 429 — превышение лимитов. Документация OpenCode отдельно советует убедиться, что ID провайдера в конфигурации совпадает с тем, который использовался при добавлении ключа, и что выбран правильный npm-пакет для OpenAI-совместимого API.

Полезно держать конфигурацию провайдера в репозитории и проверять её при обновлении OpenCode: набор полей и синтаксис подстановки переменных могут меняться. Если после обновления модели пропали из списка, начните с проверки options.baseURL и списка models — это самые частые причины.

• Проверьте совпадение ID провайдера в конфигурации и при добавлении ключа.
• Для /v1/chat/completions используйте @ai-sdk/openai-compatible.
• 401 — ключ, 404 — ID модели и baseURL, 429 — лимиты.
• Начинайте с короткой задачи до больших агентных сессий.

OpenCode — агент: он читает файлы и делает несколько шагов, поэтому контекст растёт быстро. Ограничивайте задачу конкретным модулем, а длинные сессии начинайте с небольшого репозитория. Баланс NeuroAPI предоплаченный, списание идёт по фактическому использованию, а история расхода доступна в кабинете.

Тариф выбирается при создании ключа. Пилот экономичнее, но допускает перебои; Оптимальный работает через официальные каналы; Смарт делает одну попытку Пилота и при безопасной ошибке переходит к цепочке Оптимального. Для работы в команде удобно завести отдельные ключи под разные проекты или разработчиков.

• Агентные сессии расходуют больше коротких вопросов.
• Ограничивайте контекст и число файлов.
• Отдельные ключи под проекты — прозрачный расход.
• Тариф — на уровне ключа, а не аккаунта.

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

В команде стоит договориться о едином наборе моделей: разные разработчики могут подключать разные ключи, но список ID лучше зафиксировать, чтобы задачи выполнялись на сопоставимых моделях. Отдельные ключи по проектам упрощают и расход, и разбор инцидентов, а baseURL при этом остаётся общим. Проверяйте конфигурацию на чистом клоне репозитория перед onboarding нового разработчика: так сразу видно, какие поля обязательны, а где ключ подставляется из окружения.

• Ключ — в переменной окружения или локальном файле.
• Попавший в git ключ отзывайте, а не только удаляйте.
• Единый список ID моделей для команды.
• Отдельные ключи по проектам — прозрачный расход.
• Сверяйте поля конфигурации после обновлений OpenCode.