Когда OpenCode с Ollama перестаёт работать, проверьте эндпоинт сервера и точный идентификатор модели, прежде чем менять модель. Если обе проверки пройдены, протестируйте небольшое редактирование файла, чтобы отделить проблему вызова инструментов от проблемы подключения. Если модель отвечает на запрос в чате, это означает лишь то, что пройдена первая часть рабочего процесса агента для кодинга.
Это руководство предполагает, что Ollama и OpenCode уже установлены. Для установки и настройки провайдера воспользуйтесь руководством по настройке Ollama с OpenCode. Описанная здесь процедура позволяет изолировать сбои без многократного изменения рабочей конфигурации.
Определите, какой именно запрос не проходит
Сбой OpenCode может произойти до инференса, во время генерации или при выполнении инструмента. Проверяйте эти этапы по отдельности. Отказ в подключении указывает на одну проблему, а модель, возвращающая абзац, похожий на JSON, — на другую. Зафиксируйте эндпоинт, выбранную модель и текст ошибки до изменения настроек, чтобы понять, помогло ли изменение.
| Наблюдение | Следующая проверка | Что подтверждает результат |
|---|---|---|
| Отказ в подключении | Запросите /api/version на настроенном хосте и порту | Доступен ли данный эндпоинт Ollama |
| Модель не найдена | Прочитайте /v1/models и сравните точный идентификатор | Существует ли запрошенная модель на этом сервере |
| Чат работает, файлы не изменяются | Проверьте вызовы инструментов и результаты разрешений | Пытался ли OpenCode выполнить действие и завершил ли его |
| Малые правки работают, крупные задачи падают | Проверьте выделенный контекст и логи рантайма | Сталкивается ли крупная задача с измеримым лимитом |
| Локально работает, в облаке зависает | Протестируйте оба маршрута отдельно | Специфичен ли сбой для облачного пути |
Зафиксируйте версии перед воспроизведением сбоя:
opencode --version
ollama --version
Локальные проверки для этой статьи проводились на OpenCode 1.19.4 и Ollama 0.32.9 на Apple M3 Ultra с 96 ГБ унифицированной памяти. Это оборудование способно запускать выбранную нами модель на 31B параметров; это не рекомендация по памяти для ноутбука с меньшими ресурсами. Для выбора модели под другое оборудование обратитесь к руководству по моделям Ollama для кодинга.
Проверьте эндпоинт, прежде чем менять модель
Отправьте запрос на тот же хост и порт, которые использует OpenCode. Локальный сервер на 127.0.0.1:11434 и сервер на 127.0.0.1:11435 — это разные эндпоинты. Если запрос не проходит, сначала восстановите сервер или адрес. Смена модели не устранит отказ сетевого подключения.
curl --fail-with-body --max-time 5 \
http://127.0.0.1:11434/api/version
curl --fail-with-body --max-time 5 \
http://127.0.0.1:11434/v1/models
Ответ с версией подтверждает, что Ollama ответил. Ответ со списком моделей подтверждает, какие идентификаторы моделей предоставляет этот сервер. Пустой список означает, что сервер доступен, но не содержит перечисленных моделей; это отличается от ошибки подключения.
Если Ollama остановлена, запустите приложение или его сервер в терминале:
ollama serve
Если порт уже занят, проверьте, какой сервер запущен, вместо запуска ещё одной копии. Удалённая установка Ollama требует указания удалённого адреса; 127.0.0.1 всегда относится к машине, на которой запущен клиент.
Документация по интеграции Ollama с OpenCode использует базовый URL, совместимый с OpenAI, оканчивающийся на /v1. Сохраняйте этот суффикс в конфигурации провайдера OpenCode. Нативные диагностические маршруты, такие как /api/version, находятся за его пределами.
Сопоставьте настроенную модель с точным идентификатором на сервере
Используйте идентификатор модели, возвращаемый сервером, включая тег. Модель, загруженная на одном сервере Ollama, недоступна на другом, если на нём нет той же модели. Проверьте выбранного провайдера, его базовый URL и объявление модели вместе, прежде чем повторять запрос.
Вот структура провайдера, которую мы использовали для проверок на OpenCode 1.19.4:
{
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"options": {
"baseURL": "http://127.0.0.1:11434/v1"
},
"models": {
"gemma4:31b": {
"name": "Gemma 4 31B",
"limit": {
"context": 65536,
"output": 2048
}
}
}
}
}
}
Замените gemma4:31b на идентификатор, который действительно присутствует в списке вашего сервера. Пример не загружает эту модель. Полный селектор OpenCode объединяет имя провайдера и идентификатор модели:
opencode run -m ollama/gemma4:31b "Reply with one short sentence."
Мы намеренно запросили отсутствующую модель через совместимый эндпоинт Ollama и получили HTTP 404 с not_found_error. Этот результат подтверждает ошибку выбора модели. Он не указывает на нехватку памяти или неисправный парсер инструментов.
Конфигурации также могут поступать из нескольких источников. Документация по конфигурации OpenCode описывает, как настройки объединяются. Проверьте итоговую конфигурацию локально, если какое-либо значение, похоже, игнорируется:
opencode debug config
Итоговая конфигурация может содержать учётные данные. Извлеките релевантные настройки провайдера перед отправкой диагностического отчёта и удалите ключи или несвязанные данные аккаунта.
Проверьте действие с помощью одноразовой фикстуры для кодинга
Проверьте изменённый файл и запустите его тест самостоятельно. Дайте OpenCode крошечный файл с одним известным багом, попросите исправить его и выполните независимую проверку. Это тестирует доступ к файлам, редактирование и выполнение, сохраняя диагностику достаточно компактной для инспекции.
Создайте новую директорию и перейдите в неё:
mkdir opencode-ollama-check
cd opencode-ollama-check
cat > add.mjs <<'JS'
export function add(a, b) {
return a - b;
}
JS
cat > check.mjs <<'JS'
import { add } from './add.mjs';
if (add(2, 3) !== 5) throw new Error('Expected add(2, 3) to return 5');
console.log('PASS');
JS
node check.mjs
Первая проверка должна завершиться неудачей. Скопируйте проверенную конфигурацию провайдера в эту одноразовую директорию, затем выполните:
opencode run -m ollama/gemma4:31b \
"Read add.mjs. Fix add so it adds its arguments. Run node check.mjs."
node check.mjs
Проверьте add.mjs самостоятельно. Сообщение об успехе от модели недостаточно, если файл по-прежнему вычитает или независимая проверка не проходит. Не скрывайте запросы на разрешение, чтобы отличить отклонённое редактирование от отсутствующего вызова инструмента. Во время наших проверок macOS разрешала фикстуру по пути /private/tmp, тогда как инструмент запрашивал её алиас /tmp. OpenCode трактовал путь с алиасом как внешний и отклонял его при неинтерактивном запуске. Использование разрешённой директории и относительных путей к файлам позволило фикстуре работать с узко ограниченными разрешениями.
Для более глубокой инспекции CLI OpenCode поддерживает вывод в формате JSON:
opencode run --format json -m ollama/gemma4:31b \
"Read add.mjs and explain the implementation."
Ищите выполненный инструмент и его результат. Текст, содержащий имя функции или JSON-объект, сам по себе не доказывает, что OpenCode что-либо выполнил. После исправления эндпоинта и разрешений фикстуры один прогон прочитал фикстуру, заменил вычитание на сложение и прошёл независимую проверку Node. Второй прогон прошёл ту же проверку после замены намеренно отсутствующего идентификатора модели. В нашем отдельном прямом запросе к API Gemma 4 31B вернула структурированный вызов read_file при контексте 65 536. Этот единственный результат подтверждает формат ответа тестового запроса, но не надёжность на всех задачах кодинга.
Проверьте контекст, который Ollama действительно выделила
Заявленный лимит модели в OpenCode и фактическое выделение в рантайме Ollama должны совпадать. Увеличение числа в конфигурации клиента не доказывает, что сервер выделил больше контекста. Проверьте загруженную модель во время запроса, затем сравните её фактический контекст с промптом задачи и историей инструментов.
Документация по контексту Ollama рекомендует не менее 64 000 токенов для инструментов и агентов кодинга. В ней также объясняется, что большее выделение потребляет больше памяти. Сервер, запущенный вручную, может задать явное выделение:
OLLAMA_CONTEXT_LENGTH=65536 ollama serve
Установите эту переменную для процесса, в котором запущена Ollama. Экспорт переменной только в терминале, где запущен OpenCode, не переконфигурирует уже работающее приложение Ollama. Используйте настройку контекста приложения, если приложение управляет вашим сервером.
Пока модель загружена, проверьте её:
ollama ps
Обратите внимание на столбцы CONTEXT и PROCESSOR. Если Ollama использует нестандартный хост или порт, направьте CLI на этот сервер. Давление на память, выгрузка на CPU, усечение и сбои формата инструментов требуют отдельных доказательств; один лишь медленный ответ не позволяет определить, что именно произошло.
Если ваше оборудование не позволяет выделить требуемый контекст, выберите модель меньшего размера с поддержкой инструментов и повторите ту же фикстуру. Не сравнивайте две модели на разных задачах, а затем объясняйте разницу качеством модели.
Составьте полезный отчёт о сбое
Полезный отчёт позволяет другому разработчику воспроизвести тот же запрос. Включите версии, очищенную конфигурацию провайдера, точный тег модели, выделенный контекст и минимальную фикстуру, которая по-прежнему не проходит. Зафиксируйте, проходит ли прямой запрос и достигает ли OpenCode сервера модели. Эти детали помогают мейнтейнерам локализовать сбой.
Руководство по устранению неполадок OpenCode объясняет, как найти логи. На протестированной версии эта команда определяет настроенные пути к данным и логам:
opencode debug paths
Разделяйте локальные и облачные результаты. Локальный тест кодинга не может подтвердить аутентификацию или доступность Ollama Cloud, а сбой в облаке не свидетельствует о регрессии локального использования инструментов. Аналогично, более ранний issue с тем же симптомом не доказывает, что предложенное в нём исправление применимо к вашей установленной версии.
Если фикстура проходит, но задача в вашем репозитории не проходит, сохраните рабочую фикстуру и постепенно добавляйте сложность: ещё один файл, больший вход или более длинную последовательность инструментов. Первое изменение, воспроизводящее сбой, полезнее, чем переустановка обоих приложений без сравнения.
Для настройки отдельного провайдера после завершения локальной диагностики руководство по пользовательским провайдерам OpenCode охватывает настройку Haimaker. Оставляйте приватные локальные тесты локальными; смена провайдера — необязательный следующий шаг, когда рабочая нагрузка это позволяет.
Часто задаваемые вопросы
Означает ли успешный чат с Ollama, что инструменты OpenCode будут работать?
Нет. Ответ в чате доказывает лишь то, что модель способна генерировать текст. OpenCode также требует структурированных вызовов инструментов, разрешения на их выполнение и достаточного контекста для задачи. Проверьте реальное редактирование файла и результат его теста.
Выделяет ли увеличение лимита контекста в OpenCode больше памяти Ollama?
Заявленный лимит контекста в OpenCode не доказывает, что Ollama выделила этот контекст. Настройте сервер Ollama и проверьте загруженную модель командой ollama ps. Больший контекст также увеличивает требования к памяти.
Стоит ли переустанавливать всё, если модель Ollama исчезла из OpenCode?
Начните со сравнения идентификаторов моделей, возвращаемых Ollama, с моделью, указанной в конфигурации OpenCode. Проверьте эндпоинт и выбранного провайдера, прежде чем переустанавливать какое-либо приложение.