Как подключить Ollama к агенту для программирования

К чему вы подключаетесь

Вы можете использовать Ollama вместе с вашим агентом для программирования, и процесс подключения проще, чем кажется. Вам нужно изменить только базовый URL и выбрать имя модели. Поле для API key по-прежнему требует ввода значения, но локальный сервер его игнорирует, поэтому подойдет любая строка.

Ollama ожидает запросы на порту 11434 и одновременно поддерживает два формата API. /v1/chat/completions — это формат, совместимый с OpenAI; в документации Ollama указано, что ключ в этом случае обязателен, но не проверяется. /v1/messages — это формат, совместимый с Anthropic, который использует Claude Code. Ваш агент уже поддерживает один из этих форматов, поэтому никаких других изменений не требуется.

Эта часть настройки занимает пять минут. Удобство использования результата зависит от двух параметров, которые почти никто не меняет: длины контекста и keep-alive, а также от того, насколько задачи соответствуют возможностям модели. Оба параметра разобраны в отдельных разделах, а честный обзор ограничений приведен в конце.

Какие агенты для написания кода поддерживают локальный base URL

Тест состоит из одного вопроса: позволяет ли инструмент задать base URL? Если да, он может взаимодействовать с вашим сервером.

Ollama публикует страницы интеграции для Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, IDE от JetBrains и VS Code. Aider документирует собственную поддержку Ollama отдельно. Это охватывает большинство инструментов, которые подразумеваются под агентами для написания кода в августе 2026 года. Они не все используют одинаковый формат запросов, и именно в этих различиях кроются причины сбоев при настройке.

• Большинству агентов требуется эндпоинт, совместимый с OpenAI. Укажите им base URL http://localhost:11434/v1 и любую непустую строку в качестве API key.
• Claude Code вообще не принимает OpenAI base URL. Он работает через Anthropic Messages API, поэтому для него необходимо установить ANTHROPIC_BASE_URL в значение http://localhost:11434, где Ollama обслуживает /v1/messages.
• Codex использует OpenAI Responses API. Ollama также поддерживает его через /v1/responses, начиная с версии 0.13.3.
• Агент без настройки base URL не может быть перенаправлен, так как эндпоинт «зашит» в клиент. В таком случае установите перед ним слой трансляции, например самохостируемый шлюз LiteLLM, и предоставьте свою модель в том формате, который требует клиент.

Ollama может создать эти конфигурации за вас. ollama launch opencode запускает OpenCode с встроенной конфигурацией для выбранной вами модели, ollama launch claude делает то же самое для Claude Code, а ollama launch droid --config записывает конфигурацию без запуска самого инструмента.

Установка Ollama и загрузка модели с поддержкой вызова инструментов

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

Установщик добавляет unit для systemd и запускает его, поэтому systemctl status ollama должен вывести active (running). Если этого не происходит, journalctl -e -u ollama покажет причину ошибки.

Модель должна поддерживать вызов инструментов (tool calling), так как именно на этом механизме работают агенты. Агент читает файл, создает патч, запускает тест, затем анализирует ошибку и повторяет попытку. Модель, не способная генерировать вызовы инструментов, будет описывать изменения в тексте вместо их выполнения, из-за чего агент зациклится или остановится. Перед загрузкой проверьте наличие метки tools на странице модели на сайте ollama.com. Модель qwen3-coder:30b поддерживает эту функцию, и по состоянию на август 2026 года этот тег требует загрузки 19 GB данных и предоставляет окно контекста 256K.

Теперь подтвердите, какие именно имена моделей обслуживает сервер:

curl http://localhost:11434/v1/models

Строки в этом ответе — это именно то, что должно быть указано в конфигурации вашего агента, символ в символ. Проверка этого списка заранее устраняет большинство ошибок вида «модель не найдена». Если Ollama еще не установлена, подробное руководство доступно в разделе самостоятельный хостинг LLM с помощью Ollama на VPS.

Настройка OpenCode для работы с Ollama

Отредактируйте ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "qwen3-coder 30b"
        }
      }
    }
  }
}

Значение ключа в models — это имя модели, которое отправляется в Ollama, поэтому оно должно в точности совпадать с ollama ls. Поле name является лишь меткой в меню выбора модели. Запустите opencode, переключитесь на провайдера Ollama и следите за journalctl -e -u ollama, чтобы убедиться, что запрос поступил на ваш сервер, а не куда-либо еще. Настройка самого агента описана в разделе запуск OpenCode на VPS.

Настройка Claude Code для работы с Ollama

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

Переменная ANTHROPIC_API_KEY намеренно оставлена пустой. Если оставить в окружении реальный ключ, запросы будут отправляться к облачному API, что приведет к списанию средств вместо использования локального вывода. Команда ollama launch claude настраивает всё это автоматически.

Учитывайте ограничения уровня совместимости. Он не реализует tool_choice или кэширование промптов, а также не имеет эндпоинта для подсчета токенов, поэтому отображаемые значения являются приблизительными оценками, полученными от собственного токенизатора модели. Claude Code также использует объемный системный промпт и широкий набор инструментов, поэтому ему требуется больше контекста, чем обычному чат-клиенту. Более подробный разбор того, какие функции поддерживаются, а какие нет, приведен в разделе возможность самостоятельного хостинга Claude.

Настройка Aider для работы с Ollama

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

Документация Aider рекомендует использовать префикс ollama_chat/ вместо ollama/. Также инструмент позволяет задавать размер контекстного окна для каждой модели в .aider.model.settings.yml. Это полезно, если для конкретной модели требуется значение, отличное от заданного по умолчанию на сервере:

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

Почему рабочая конфигурация выдает бессвязные ответы

Это ключевой раздел. Ollama выбирает длину контекста по умолчанию исходя из объема VRAM (видеопамяти GPU), который она обнаруживает. Эти значения по умолчанию опубликованы:

[
  {
    "label": "Under 24 GiB VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "24 to 48 GiB VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "48 GiB VRAM or more",
    "default_context_tokens": "262,144"
  }
]

Большинство тарифных планов VPS и все серверы без GPU попадают в первую строку: 4,096 токенов. Только мощные GPU получают 262,144 токенов из последней строки.

Агент расходует 4096 токенов еще до начала работы. Системный промпт, определения инструментов, список репозитория и первый открытый файл уже превышают этот лимит. Дальше происходит основная проблема: система не выдает ошибок. В документации Aider указано, что Ollama молча отбрасывает контекст, выходящий за пределы окна. Самые старые токены удаляются, поэтому модель уверенно рассуждает о файле, который она больше не «видит», или забывает инструкцию, данную двумя шагами ранее. Этот механизм — причина большинства жалоб на то, что локальная модель «слишком глупа» для написания кода.

Документация Ollama гласит, что для таких задач, как работа агентов и инструментов программирования, следует устанавливать значение не менее 64000 токенов. Установите его на сервере:

sudo systemctl edit ollama.service

Добавьте эти строки в файл переопределения:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Затем выполните перезагрузку конфигурации и перезапуск:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps используется для проверки. Она выводит столбец CONTEXT — это число токенов, которые модель фактически получила. Ваши значения ID и SIZE будут различаться:

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

Устанавливайте это значение на сервере, а не в агенте, по двум причинам. В схеме OpenAI chat completions нет поля для длины контекста, поэтому клиент, совместимый с OpenAI, не может запросить его. Кроме того, настройка применяется на уровне сервера, поэтому каждый агент, направленный на этот узел, наследует её. Если какой-то модели требуется другое окно, задайте его в копии через Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Контекст не бесплатен. Увеличенное окно требует больше памяти, поэтому следите за столбцом PROCESSOR. 100% GPU — это желаемый показатель. Как только часть модели вытесняется в CPU, скорость генерации токенов падает настолько, что цикл работы агента становится непригодным для использования. Измерение количества токенов в секунду для локальной LLM — это способ найти реальный предел возможностей вашего оборудования. Подбор характеристик машины перед покупкой описан в какой объем RAM и CPU нужен для VPS с агентом для программирования.

Удержание модели в памяти между запросами

По умолчанию Ollama выгружает модель через 5 минут после последнего запроса. Это подходит для чат-бота, но не для работы агентов. Вы делаете паузу, чтобы прочитать diff, таймер истекает, и следующий запрос перезагружает десятки гигабайт весов с диска перед генерацией первого токена. Это выглядит как зависание.

OLLAMA_KEEP_ALIVE принимает строку длительности, например 10m или 24h, простое число секунд, -1 для удержания модели в памяти на неопределенный срок или 0 для немедленной выгрузки. Установите этот параметр рядом с длиной контекста:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

Поле запроса keep_alive существует только в нативных эндпоинтах /api/generate и /api/chat Ollama, но не в эндпоинтах совместимости, поэтому агент не может задать его для каждого запроса. Переменная окружения — единственный доступный вам рычаг. Когда вам нужно освободить память, ollama stop qwen3-coder:30b выгружает модель, не останавливая сервер.

Запуск Ollama на отдельном сервере

Ollama привязывается к localhost. Чтобы получить доступ к ней с другой машины, установите OLLAMA_HOST=0.0.0.0:11434 в том же файле переопределения systemd и перезапустите службу.

Делайте это только в частной сети. В документации Ollama указано, что для локального API аутентификация не требуется, поэтому открытый в интернет порт 11434 означает, что любой может использовать ваше оборудование и читать всё, что отправляет ваш агент. Есть два безопасных варианта. Оставьте привязку к localhost и перенаправьте порт через SSH со своего ноутбука:

ssh -N -L 11434:localhost:11434 you@your-vps

Ваш агент продолжит обращаться к http://localhost:11434/v1 и не заметит разницы. Другой вариант — VPN, где Ollama привязана к адресу VPN вместо 0.0.0.0. Если один сервер будут использовать несколько человек или несколько агентов, имейте в виду, что планировщик Ollama не рассчитан на такую нагрузку, и сравнение Ollama и vLLM показывает, на каком этапе разница в пропускной способности становится критичной.

В каких случаях локальная модель кодирования эффективна, а в каких нет

Агент, работающий на базе модели, которую вы разместили самостоятельно, не заменяет API передовых моделей для любой задачи. Он явно выигрывает в четырех типах работы.

• Массовые механические правки, где каждое изменение незначительно и его можно проверить. Переименование по всему репозиторию, добавление подсказок типов, написание docstrings, перевод комментариев. Модель может работать часами, а счет за использование ресурсов не изменится.
• Работа, которая не должна покидать ваше оборудование. Клиентский код в рамках соглашения о конфиденциальности или внутренний репозиторий, который запрещено передавать третьим лицам.
• Автономные машины и системы с «воздушным зазором» (air-gapped), где нет доступа к внешнему API.
• Предсказуемая стоимость. После оплаты сервера агент, который расходует токены в цикле, не требует дополнительных затрат, что противоположно модели тарификации API. В Когда GPU VPS окупается по сравнению с токенами API приведены соответствующие расчеты.

Локальная модель проигрывает в длинных многоэтапных задачах. Запрос «найди причину сбоя теста, исправь её, обнови вызывающие функции» требует множества последовательных корректных вызовов инструментов при сохранении всей истории в контексте. Модель в диапазоне от 8B до 14B параметров на скромном сервере выдаст некорректный вызов инструмента или потеряет план действий через несколько итераций, и вы потратите на управление ею больше времени, чем заняло бы выполнение задачи. Это не проблема промпта, которую можно решить подбором текста. Это ограничение вычислительной мощности.

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

Режимы сбоев и сообщения, которые вы увидите

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Сервер не запущен или агент настроен на другой хост. Выполните systemctl status ollama, затем journalctl -e -u ollama.

Агент сообщает, что модель не существует. Имя в вашей конфигурации не совпадает с именем, которое отдает сервер. Сравните его с curl http://localhost:11434/v1/models и скопируйте строку оттуда. Тег является частью имени, поэтому конфигурация с тегом, который вы не загружали, вызовет ошибку, даже если установлена похожая модель.

Агент отвечает текстом и не редактирует файл. Либо модель не поддерживает инструменты, либо запрос вместе с определениями инструментов уже заполняет контекстное окно. Проверьте метку tools на странице модели, затем проверьте столбец CONTEXT в ollama ps.

Длинная пауза перед первым токеном, затем нормальная скорость. Время ожидания keep-alive истекло, и веса снова считываются с диска. Установите OLLAMA_KEEP_ALIVE.

Модель противоречит файлу, который только что прочитала. Усечение контекста. ollama ps обычно показывает значение CONTEXT меньше, чем вы ожидали, так как переменная окружения была применена к вашей оболочке, а не к юниту systemd.

Все работает, но медленно, и PROCESSOR не равно 100% GPU. Модель вместе с контекстом не помещается в VRAM. Уменьшите длину контекста или перейдите на модель меньшего размера или с меньшей квантованием.

FAQ

Можно ли подключить Claude Code к Ollama?

Да, но не через URL, совместимый с OpenAI. Claude Code использует Anthropic Messages API, и Ollama предоставляет этот интерфейс по адресу /v1/messages на том же порту 11434. Экспортируйте ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama и пустой ANTHROPIC_API_KEY, затем запустите его с помощью claude --model qwen3-coder:30b. ollama launch claude запишет эти настройки за вас. Уровень совместимости не реализует tool_choice или кэширование промптов, а также не имеет эндпоинта для подсчета токенов, поэтому отображаемое количество токенов является приблизительным.

Почему моя локальная модель отвечает на вопросы о коде, который она не видит?

Потому что запрос перестал помещаться в контекстное окно, и его самая старая часть была отброшена без ошибки. Ollama устанавливает контекст по умолчанию исходя из объема обнаруженной видеопамяти (VRAM), и при объеме менее 24 GiB это значение составляет 4,096 токенов, что уже превышается системным промптом агента и определениями инструментов. Установите OLLAMA_CONTEXT_LENGTH=64000 в юните systemd, перезапустите Ollama и убедитесь, что столбец CONTEXT в ollama ps показывает новое значение.

Какую модель выбрать для работы агента программирования на VPS?

Выберите самую большую модель с меткой tools, которая помещается в память при контекстном окне 64k, и отдавайте предпочтение моделям, дообученным для работы с кодом. qwen3-coder:30b — распространенный выбор для сервера с GPU, обладающего достаточным объемом VRAM. При количестве параметров менее 14B модель может хорошо отвечать на вопросы о коде, но ошибаться при многошаговом редактировании, так как работа агента критична к мелким ошибкам форматирования в вызовах инструментов. Протестируйте модель на реальной задаче из вашего собственного репозитория, а не на демонстрационном промпте.

Нужен ли GPU для запуска агента программирования на своей модели?

На практике — да. Инференс только на CPU работает и подходит для разовых вопросов, но агент отправляет множество запросов для выполнения одной задачи, и каждый из них заново считывает длинную историю. Низкая скорость генерации токенов превратит двухминутную задачу в часовую. Проверьте столбец PROCESSOR в ollama ps: любое значение, отличное от 100% GPU, означает, что часть модели выполняется на CPU, и скорость генерации токенов резко падает.