Як підключити Ollama до coding agent

Що саме ви підключаєте

Ollama можна використовувати з вашим coding agent, і підключення простіше, ніж може здаватися. Потрібно змінити одну базову URL-адресу та вибрати назву моделі. Поле для API key все одно потребує значення, але локальний сервер його ігнорує, тому підійде будь-який рядок.

Ollama прослуховує порт 11434 і одночасно обробляє два формати запитів. /v1/chat/completions — це OpenAI-сумісний формат. У документації Ollama зазначено, що key у ньому обов’язковий, але ігнорується. /v1/messages — це Anthropic-сумісний формат, який використовує Claude Code. Ваш agent уже працює з одним із цих форматів, тому інші його налаштування змінювати не потрібно.

Це налаштовується за п’ять хвилин. Практична придатність результату залежить від двох параметрів, які майже ніхто не змінює: довжини контексту та keep-alive. Також важливо доручати моделі роботу, для якої вона підходить. Кожному з цих параметрів присвячено окремий розділ. Наприкінці наведено чесний опис обмежень.

Які coding agents підтримують локальний base URL

Перевірка зводиться до одного питання: чи має інструмент параметр base URL? Якщо так, він може підключатися до вашого сервера.

Ollama публікує сторінки інтеграції для Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, JetBrains IDEs і VS Code. Aider окремо документує власну підтримку Ollama. Це охоплює більшість інструментів, які станом на серпень 2026 року називають coding agent. Вони використовують різні формати підключення, і саме через цю різницю конфігурації часто не працюють.

• Більшість агентів потребує OpenAI-compatible endpoint. Вкажіть їм 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 не можна перенаправити, оскільки endpoint вбудований у клієнт. Натомість розмістіть перед ним translation layer, наприклад self-hosted шлюз LiteLLM, і повторно надайте ваш model у форматі, якого потребує клієнт.

Ollama може створити ці конфігурації за вас. ollama launch opencode запускає OpenCode з inline config для вибраної моделі, 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 виведе причину.

Модель має підтримувати виклики інструментів, оскільки саме так працює агент. Він читає файл, записує patch, запускає тест, потім читає повідомлення про помилку і повторює спробу. Модель, яка не може сформувати виклик інструмента, опише зміни текстом замість того, щоб виконати їх, і агент зациклиться або зупиниться. Перед завантаженням знайдіть мітку tools на сторінці моделі на ollama.com. Її має qwen3-coder:30b, а станом на August 2026 ця мітка означає завантаження розміром 19 GB із контекстним вікном 256K. Якщо ваш сервер працює лише на CPU або має мало RAM, арифметика використання пам’яті для мітки Qwen 27B на VPS показує, що фактично поміститься в 8–64 GB, перш ніж ви почнете завантаження. Після завантаження ці гігабайти займуть місце на root-диску сервера. Саме на цій частині VPS зазвичай найменше вільного простору, тому перед заповненням диска варто прочитати матеріал де Ollama зберігає файли моделей і як перемістити їх в інше місце.

Тепер перевірте, які імена сервер фактично обслуговує:

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

Рядки у відповіді мають бути в конфігурації агента без жодної зміни. Попередня перевірка усуває більшість помилок model-not-found. Якщо Ollama ще не встановлено, докладніші інструкції наведено в матеріалі self-hosting 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 навмисно встановлено в порожній рядок. Якщо в середовищі залишиться справжній ключ, запити натомість буде надіслано до hosted API. У результаті ви отримаєте рахунок і не використовуватимете локальний inference. ollama launch claude налаштовує все це автоматично.

Враховуйте обмеження compatibility layer. Він не реалізує tool_choice або prompt caching і не має endpoint для підрахунку токенів. Тому кількість токенів, яку ви бачите, є приблизною оцінкою на основі власного tokenizer моделі. Claude Code також передає великий system prompt і великий набір інструментів, тому йому потрібно більше context, ніж chat client. Докладніше про те, що можна перенести, а що ні, див. у матеріалі чи можна self-host Claude.

Вкажіть Ollama для Aider

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-планів і кожен сервер лише з CPU потрапляють у перший рядок: 4,096 токенів. Лише потужний GPU отримує 262,144 токенів з останнього рядка.

Агент передає 4096 токенів ще до початку роботи. Системний prompt, визначення інструментів, список репозиторію та перший відкритий файл уже перевищують цей обсяг. Далі виникає основна проблема: жодної помилки немає. У документації Aider зазначено, що Ollama мовчки відкидає контекст, який виходить за межі вікна. Найстаріші токени випадають, тому модель впевнено відповідає про файл, якого вже не бачить, або забуває інструкцію, надану два кроки тому. Саме цей механізм лежить в основі більшості повідомлень про те, що локальна модель надто погано пише код. Вибір самого значення — окреме рішення, а вартість num_ctx у пам’яті KV cache для кожного розміру варто оцінити, перш ніж остаточно його встановлювати.

У документації Ollama зазначено, що для таких завдань, як робота агентів і coding tools, слід встановлювати щонайменше 64000 токенів. Встановіть це значення на сервері:

sudo systemctl edit ollama.service

Додайте ці рядки у файл override:

[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-compatible client не може її запитати. Крім того, це налаштування застосовується на рівні сервера, тому його успадкує кожен агент, підключений до цього сервера. Для вихідних даних є окреме обмеження. На відміну від довжини контексту, воно передається через compatibility endpoint. Тому, якщо відповідь обривається посеред patch, слід використовувати 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 для coding agent VPS.

Зберігайте модель завантаженою між запитами

За замовчуванням Ollama вивантажує модель через 5 minutes після останнього запиту. Для вікна чату це правильно, але для роботи агента — ні. Ви призупиняєте роботу, щоб переглянути diff, таймер спливає, а наступний запит знову завантажує з диска десятки gigabytes ваг моделі, перш ніж з’явиться перший токен. Це виглядає як зависання.

OLLAMA_KEEP_ALIVE приймає рядок тривалості, наприклад 10m або 24h, звичайне число секунд, -1 для безстрокового збереження моделі завантаженою або 0 для негайного вивантаження. Вкажіть цей параметр поруч із довжиною контексту:

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

Поле запиту keep_alive існує лише в нативних endpoint'ах Ollama /api/generate і /api/chat, але не в endpoint'ах сумісності, тому агент не може встановлювати його для окремого запиту. Змінна середовища — єдиний доступний параметр керування. Коли потрібно звільнити пам’ять, ollama stop qwen3-coder:30b вивантажує модель, не зупиняючи сервер. Якщо потрібно зберігати це налаштування після перезавантаження або вирішити, чи варто тримати ваги в пам’яті весь день, чи краще звільнити цю пам’ять, збереження моделі Ollama завантаженою в пам’яті працює в обох випадках.

Запуск Ollama на окремому сервері

Ollama прив’язується до localhost. Щоб отримати доступ до нього з іншої машини, задайте OLLAMA_HOST=0.0.0.0:11434 у тому самому systemd override і перезапустіть сервіс.

Робіть це лише в приватній мережі. У документації Ollama зазначено, що локальний API не потребує автентифікації. Тому порт 11434, відкритий в інтернет, дає змогу будь-кому використовувати ваше обладнання та читати все, що надсилає ваш агент. Є 2 безпечні варіанти. Залиште прив’язку до 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 показує, на якому етапі різниця в пропускній здатності стає відчутною.

Коли локальна coding model виграє, а коли — ні

Агент на базі моделі, яку ви розміщуєте самостійно, не замінює frontier API для кожного завдання. Він явно виграє у чотирьох видах роботи.

• Масові механічні зміни, де кожна зміна невелика, а результат можна перевірити. Перейменування в репозиторії, додавання type hints, написання docstrings, переклад коментарів. Модель може працювати годинами, а рахунок не збільшується.
• Робота, дані якої не повинні залишати ваше обладнання. Наприклад, клієнтський код під дією угоди про конфіденційність або внутрішній репозиторій, який заборонено надсилати третій стороні.
• Офлайн- та air-gapped машини, де взагалі немає hosted API, до якого можна звернутися.
• Передбачувана вартість. Після оплати сервера агент, який витрачає токени в циклі, не створює додаткових витрат. Це протилежність API з оплатою за використання. У розділі Коли GPU VPS стає вигіднішим за API-токени наведено розрахунок.

Він програє на тривалих багатокрокових завданнях. Запит «знайди причину збою тесту, виправ її та онови виклики» потребує багатьох правильних tool calls поспіль, причому вся історія має залишатися в контексті. Модель діапазону 8B–14B на помірному за характеристиками сервері може сформувати некоректний tool call або втратити план через кілька кроків. У результаті ви витратите на керування нею більше часу, ніж зайняло б саме завдання. Це не проблема prompt, яку можна усунути правильним формулюванням. Це обмеження capacity.

Вона також програє щоразу, коли помилка дорого коштує, а ви не читатимете кожен рядок. Доручайте локальній моделі вузькі завдання, результат яких ви перевіряєте, а hosted model залишайте для роботи, яку ви не перевірятимете крок за кроком.

Режими відмов і повідомлення, які ви побачите

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, менше за встановлене вами, тому що змінна середовища потрапила до вашої shell-сесії, а не до systemd unit.

Усе працює повільно, а PROCESSOR не дорівнює 100% GPU. Модель разом із контекстом не вміщується у VRAM. Зменште довжину контексту або перейдіть на меншу модель чи меншу quantisation. Перш ніж повторно завантажувати модель, у матеріалі скільки пам’яті потребують q4_K_M, q8_0 і fp16 та де фактично знижується якість пояснено, скільки простору дає перехід на нижчий рівень і від чого доведеться відмовитися.

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 або кешування промптів і не має endpoint для підрахунку токенів, тому показники кількості токенів є приблизними.

Чому моя локальна модель відповідає про код, якого вона не бачить?

Тому що запит більше не вміщується у вікно контексту, а його найстарішу частину було вилучено без повідомлення про помилку. Ollama визначає контекст за замовчуванням на основі доступної VRAM. Якщо її менше ніж 24 GiB, значення за замовчуванням становить 4,096 токенів. Системний промпт агента та визначення інструментів самі по собі перевищують це значення. Задайте OLLAMA_CONTEXT_LENGTH=64000 у systemd unit, перезапустіть Ollama і перевірте, що в колонці CONTEXT у ollama ps показано нове значення.

Яку модель запускати для coding agent на VPS?

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

Чи потрібен GPU, щоб запускати coding agent на власній моделі?

На практиці так. Інференс лише на CPU працює і підходить для окремих запитань, але агент надсилає багато запитів для одного завдання, і кожен запит повторно обробляє довгу історію. Тому низька швидкість генерації токенів може збільшити тривалість двохвилинного завдання до однієї години. Перевірте колонку PROCESSOR у ollama ps: будь-яке значення, відмінне від 100% GPU, означає, що частина моделі працює на CPU, а швидкість генерації токенів різко знижується.