Як підключити 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. Це охоплює більшість інструментів, які станом на August 2026 називають coding agent. Вони використовують різні формати API, і саме через цю відмінність конфігурації часто не працюють.

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

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

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

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 навмисно задано як порожній рядок. Якщо в середовищі залишити справжній ключ, запити буде надіслано до розміщеного API. У результаті ви отримаєте рахунок за використання API, а локальний запуск моделі не працюватиме. ollama launch claude налаштовує все це автоматично.

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

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

У документації Ollama зазначено, що для таких завдань, як робота агентів та інструментів програмування, слід встановити щонайменше 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 не може запросити це значення. Крім того, параметр діє на рівні сервера, тому його успадковує кожен агент, підключений до цього сервера. Якщо для однієї моделі потрібне інше вікно, зафіксуйте це значення в копії моделі за допомогою 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 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 показує, на якому етапі різниця в пропускній здатності стає проблемою.

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

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

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

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

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

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

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

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

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

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

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