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

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

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

Ollama ожидает соединения на порту 11434 и одновременно предоставляет три API-интерфейса. /api — это собственный API Ollama. /v1 — это слой, совместимый с OpenAI, который охватывает несколько форматов: /v1/chat/completions, /v1/responses, /v1/completions, /v1/models и /v1/embeddings. В документации Ollama указано, что ключ в данном случае является обязательным, но игнорируется. Третий интерфейс совместим с Anthropic: клиент использует http://localhost:11434 в качестве базового URL и добавляет /v1/messages, что соответствует протоколу Claude Code. Большинство агентов используют /v1/chat/completions, Codex использует /v1/responses, а Claude Code использует /v1/messages. Ваш агент уже поддерживает один из этих протоколов, поэтому никаких других изменений не требуется.

Эта часть занимает пять минут. Возможность использования результата зависит от двух настроек, которые почти никто не меняет: длины контекста (context length) и времени удержания модели в памяти (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 не может быть перенаправлен, так как эндпоинт «зашит» в клиент. Если агент принимает пользовательский URL, но требует другой формат API, установите перед ним слой трансляции, например самостоятельно развернутый шлюз 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 намеренно оставлен пустым. Базовый URL определяет адрес отправки запросов; очистка этого ключа предотвращает передачу учетных данных облачных сервисов в локальную среду. 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 запрашивает объем контекста, достаточный для каждого запроса, плюс 8k токенов для ответа. Также можно зафиксировать размер окна контекста для каждой модели в .aider.model.settings.yml. Это полезно, если для конкретной модели требуется окно, отличное от заданного по умолчанию на сервере:

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

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

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

[
  {
    "label": "Under 23 GiB aggregate VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "23 to under 47 GiB aggregate VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "47 GiB aggregate VRAM or more",
    "default_context_tokens": "262,144"
  }
]

Большинство тарифных планов VPS и все серверы без GPU попадают в первую строку: 4,096 токенов. Несколько небольших GPU в сумме могут достичь порога в 47 GiB для 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, чтобы в памяти была загружена модель для проверки. 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 существует в нативных эндпоинтах Ollama /api/generate и /api/chat, а также как расширение Ollama в /v1/chat/completions. Агент, поддерживающий дополнительные поля запроса, может передать его туда; в противном случае используйте переменную окружения. Когда вам нужно освободить память, 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. Если PROCESSOR показывает 100% CPU на машине с GPU, сначала исключите другую причину: Ollama могла вовсе не обнаружить GPU. В документации Ollama указано, что в Linux после цикла приостановки/возобновления работы (suspend/resume) она иногда не может обнаружить GPU NVIDIA и переключается на CPU, и что перезагрузка драйвера с помощью sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm позволяет обойти эту проблему. Если GPU обнаружен, но распределение памяти остается прежним, уменьшите длину контекста или перейдите на модель меньшего размера или с меньшей квантованием. Перед повторной загрузкой, сколько памяти требуют 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 устанавливает контекст по умолчанию на основе общего объема обнаруженной видеопамяти после вычитания настроенных накладных расходов на каждый GPU: менее 23 GiB — по умолчанию 4,096 токенов, от 23 до менее 47 GiB — 32,768 токенов, а при 47 GiB и более — 262,144 токенов. Установите OLLAMA_CONTEXT_LENGTH=64000 в юните systemd, перезапустите Ollama и убедитесь, что столбец CONTEXT в ollama ps показывает новое значение.

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

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

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

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