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

Что именно вы подключаете

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

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

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

Какие инструменты для написания кода поддерживают локальный базовый URL

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

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

• Большинству агентов требуется эндпоинт, совместимый с OpenAI. Укажите им базовый URL http://localhost:11434/v1 и любую непустую строку в качестве API-ключа.
• Claude Code не принимает базовый URL в формате OpenAI. Он работает через Anthropic Messages API, поэтому для него необходимо установить ANTHROPIC_BASE_URL в значение http://localhost:11434, где Ollama предоставляет /v1/messages.
• Codex использует OpenAI Responses API. Ollama также предоставляет /v1/responses, начиная с версии 0.13.3.
• Агент без настройки базового 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 ГБ данных и предоставляет окно контекста 256K. Если ваш сервер работает только на CPU или имеет ограниченный объем оперативной памяти, расчет требований к памяти для тега Qwen 27B на VPS поможет понять, что именно поместится в объем от 8 до 64 ГБ, прежде чем вы начнете загрузку. После загрузки эти гигабайты сохраняются на корневом разделе диска сервера — это часть VPS, где обычно меньше всего свободного места, поэтому информация о том, где Ollama хранит файлы моделей и как перенести их в другое место будет полезна до того, как диск окажется переполнен.

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

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 позволяет задавать размер контекстного окна для каждой модели в .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 молча отбрасывает контекст, выходящий за пределы окна. Самые старые токены удаляются, поэтому модель уверенно отвечает по файлу, который она больше не «видит», или забывает инструкцию, данную двумя шагами ранее. Именно этот механизм является причиной большинства жалоб на то, что локальная модель «слишком глупа» для написания кода. Выбор конкретного числа — отдельная задача, и информацию о том, сколько KV-кэша занимает num_ctx при разных размерах стоит изучить перед принятием решения.

Документация 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-совместимый клиент не может его запросить. Кроме того, настройка применяется ко всему серверу, поэтому любой агент, направленный на этот узел, унаследует её. У стороны вывода есть свой лимит, и, в отличие от длины контекста, он передается через endpoint совместимости, поэтому num_predict и поле max_tokens, которое с ним соотносится — это то, что нужно настраивать, если ответ обрывается на середине патча. Если одной конкретной модели требуется другое окно, создайте её копию с помощью 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 на отдельном сервере

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. Уменьшите длину контекста или перейдите на меньшую модель или модель с меньшей квантованием. Перед повторной загрузкой, сколько памяти занимают q4_K_M, q8_0 и fp16 и где именно падает качество покажет, сколько места освободит переход на шаг ниже и чем придется пожертвовать.

FAQ

Можно ли направить Claude Code на Ollama?

Да, но не через URL, совместимый с OpenAI. Claude Code использует API Anthropic Messages, и 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. Если этот тег слишком велик для вашего сервера, данные об использовании RAM и скорости работы только на CPU для Nemotron 3.5 Lightning будут полезны для сравнения перед тем, как вы начнете загрузку. При количестве параметров менее 14B модель может хорошо отвечать на вопросы о коде, но ошибаться при многошаговом редактировании, так как агентная работа чувствительна к мелким ошибкам форматирования в вызовах инструментов. Протестируйте модель на одной реальной задаче из вашего собственного репозитория, а не на тестовом промпте.

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

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