Як підключити Ollama до coding agent
Дізнайтеся, як підключити coding agent до Ollama: base URL, фіктивний API key, небезпечне обмеження контексту та задачі, де локальна модель краща.
Що ви підключаєте
Ollama можна використовувати з вашим coding agent, і підключення простіше, ніж зазвичай очікують. Потрібно змінити одну базову 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 — саме цей endpoint використовує Claude Code. Більшість агентів використовує /v1/chat/completions, Codex використовує /v1/responses, а Claude Code — /v1/messages. Ваш агент уже підтримує один із цих інтерфейсів, тому більше нічого в ньому змінювати не потрібно.
Це налаштування займає п’ять хвилин. Придатність результату залежить від двох параметрів, які майже ніхто не змінює: довжини контексту та keep-alive. Вона також залежить від того, чи доручаєте ви моделі роботу, для якої вона підходить. Кожному з цих параметрів присвячено окремий розділ, а реальні обмеження наведено наприкінці.
Які coding agents приймають локальний base URL
Перевірка складається з одного запитання: чи має інструмент параметр base URL? Якщо так, він може взаємодіяти з вашим сервером.
Ollama публікує сторінки інтеграції для Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, JetBrains IDEs і VS Code. Aider окремо документує підтримку Ollama. Це охоплює більшість інструментів, які станом на October 2026 називають coding agent. Вони використовують різні формати API, і саме через цю відмінність конфігурації часто не працюють.
- Більшість agents потребують 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. - Agent без параметра base URL не можна перенаправити, оскільки endpoint вбудований у клієнт. Якщо agent приймає custom URL, але потребує іншого формату API, натомість розмістіть перед ним translation layer, наприклад self-hosted шлюз LiteLLM, і повторно надайте вашу модель у форматі, якого потребує клієнт.
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, а станом на October 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 ще не встановлено, докладніші інструкції наведено в матеріалі як розгорнути власний 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:30bANTHROPIC_API_KEY навмисно задано як порожній рядок. Базова URL-адреса визначає, куди надсилаються запити. Очищення цього ключа не дає hosted credentials потрапити до цієї локальної конфігурації. ollama launch claude налаштовує все автоматично.
Враховуйте обмеження compatibility layer. Він не реалізує tool_choice або prompt caching і не має endpoint для підрахунку токенів. Тому кількість токенів, яку ви бачите, є приблизною оцінкою на основі власного tokenizer моделі. Claude Code також передає великий system prompt і великий набір інструментів, тому йому потрібно більше контексту, ніж chat client. Ширше питання про те, що переноситься, а що ні, розглянуто в матеріалі чи можна self-host 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-планів і кожен сервер лише з CPU потрапляють у перший рядок: 4,096 токенів. Кілька менш потужних GPU разом можуть досягти порога 47 GiB і забезпечити 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, щоб завантажити модель для перевірки. ollama ps — це потрібна перевірка. Вона виводить стовпець CONTEXT, і це значення показує, що модель фактично отримала. Ваші значення ID і SIZE відрізнятимуться:
NAME ID SIZE PROCESSOR CONTEXT RUNNER UNTIL
qwen3-coder:30b a1b2c3d4e5f6 24 GB 100% GPU 64000 ggml 4 minutes from nowУстановлюйте це значення на сервері, а не в агенті, з двох причин. Схема OpenAI chat completions не має поля для довжини контексту, тому OpenAI-compatible клієнт не може його передати. Крім того, значення за замовчуванням на сервері застосовується до кожного агента, якщо модель або запит його не перевизначають. Для вихідних даних є власне обмеження, і, на відміну від довжини контексту, воно передається через compatibility endpoint. Тому num_predict і поле max_tokens, яке йому відповідає слід використовувати, коли відповідь обривається посеред patch. Якщо для однієї моделі потрібне інше вікно, зафіксуйте його в копії за допомогою Modelfile:
FROM qwen3-coder:30b
PARAMETER num_ctx 65536ollama create qwen3-coder-64k -f ModelfileКонтекст не є безкоштовним. Довше вікно потребує більше пам’яті, тому стежте за стовпцем PROCESSOR. 100% GPU — це потрібний показник. Коли частина моделі переміщується до CPU, швидкість обробки токенів знижується настільки, що цикл роботи агента стає непридатним. Щоб визначити фактичну межу для вашого сервера, скористайтеся вимірюванням кількості токенів за секунду для локальної LLM. Потреби в ресурсах машини до її придбання розглянуто в матеріалі скільки RAM і CPU потрібно VPS для coding agent.
Не вивантажуйте модель між запитами
За замовчуванням 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 override і перезапустіть сервіс.
Виконуйте це лише в приватній мережі. У документації 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 показано, у яких випадках різниця в пропускній здатності починає впливати на роботу.
Коли локальна 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.
Довга пауза перед першим токеном, а потім нормальна швидкість. Час підтримання активності завершився, і ваги знову зчитуються з диска. Встановіть OLLAMA_KEEP_ALIVE.
Модель суперечить файлу, який щойно прочитала. Це усічення контексту. ollama ps зазвичай показує значення CONTEXT, менше за те, яке, на вашу думку, ви встановили, оскільки змінна середовища потрапила до вашої оболонки, а не до unit systemd.
Усе працює, але повільно, і PROCESSOR показує 100% CPU або розподіл між CPU і GPU. Зазвичай модель разом із контекстом не поміщається у VRAM. Якщо PROCESSOR показує 100% CPU на машині з GPU, спочатку виключіть іншу причину: Ollama міг узагалі не виявити GPU. У документації Ollama зазначено, що в Linux після циклу призупинення та відновлення роботи інколи не вдається виявити NVIDIA GPU, унаслідок чого система переходить на CPU, а повторне завантаження драйвера за допомогою sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm дає змогу обійти цю проблему. Якщо GPU виявлено, але розподіл зберігається, зменште довжину контексту або перейдіть на меншу модель чи меншу квантизацію. Перед повторним завантаженням що саме q4_K_M, q8_0 і fp16 потребують у пам’яті та де фактично погіршується якість пояснює, скільки вільного місця дає перехід на нижчий рівень і від чого ви відмовляєтеся. Unknown також може бути значенням PROCESSOR; це не підтверджує вивантаження на CPU.
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 після віднімання налаштованих накладних витрат для кожного GPU: за обсягу менше 23 GiB значення за замовчуванням становить 4,096 токенів, від 23 до менш ніж 47 GiB — 32,768 токенів, а за обсягу 47 GiB або більше — 262,144 токенів. Установіть OLLAMA_CONTEXT_LENGTH=64000 в unit systemd, перезапустіть 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 працює і підходить для окремих запитань, але агент надсилає багато запитів для одного завдання, і кожен запит повторно обробляє довгу історію. Через низьку швидкість генерації токенів завдання, яке мало тривати 2 хвилини, може виконуватися годину. Перевірте стовпець PROCESSOR у ollama ps: 100% CPU або розподіл між CPU і GPU вказує на використання CPU, що сповільнює інференс. Unknown не підтверджує використання offloading на CPU.