Jak skonfigurować Ollama z agentem programistycznym

Czym jest połączenie

Ollama może współpracować z agentem programistycznym, a samo połączenie jest prostsze, niż można przypuszczać. Wymagana jest jedynie zmiana adresu base URL oraz wybór nazwy modelu. Pole API key nadal wymaga podania wartości, jednak lokalny serwer ją ignoruje, więc można wpisać dowolny ciąg znaków.

Ollama nasłuchuje na porcie 11434 i jednocześnie obsługuje dwa formaty żądań. /v1/chat/completions to format zgodny z OpenAI, w którym dokumentacja Ollama określa klucz jako wymagany, lecz ignorowany. /v1/messages to format zgodny z Anthropic, używany przez Claude Code. Agent obsługuje już jeden z tych formatów, więc żadna inna konfiguracja nie jest wymagana.

Ta część zajmuje pięć minut. Użyteczność rozwiązania zależy od dwóch ustawień, które rzadko są modyfikowane: długości kontekstu (context length) oraz parametru keep-alive, a także od przydzielenia modelowi zadań, do których jest przystosowany. Oba zagadnienia zostały omówione w osobnych sekcjach, a rzeczywiste ograniczenia przedstawiono na końcu.

Którzy agenci programistyczni akceptują lokalny adres bazowy (base URL)

Test sprowadza się do jednego pytania: czy narzędzie udostępnia ustawienie adresu bazowego? Jeśli tak, może komunikować się z Twoim serwerem.

Ollama publikuje strony integracji dla Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, środowisk JetBrains oraz VS Code. Aider dokumentuje własne wsparcie dla Ollama w oddzielnym miejscu. Obejmuje to większość narzędzi określanych mianem agentów programistycznych w sierpniu 2026 roku. Nie wszystkie korzystają z tego samego formatu komunikacji, a różnice te są przyczyną niepowodzeń w konfiguracji.

• Większość agentów wymaga punktu końcowego zgodnego z OpenAI. Należy podać im adres bazowy http://localhost:11434/v1 oraz dowolny niepusty ciąg znaków jako klucz API.
• Claude Code w ogóle nie akceptuje adresu bazowego OpenAI. Korzysta z API Anthropic Messages, więc wymaga ustawienia ANTHROPIC_BASE_URL na http://localhost:11434, gdzie Ollama udostępnia /v1/messages.
• Codex korzysta z API OpenAI Responses. Ollama udostępnia również /v1/responses, co zostało dodane w wersji 0.13.3.
• Agenta bez ustawienia adresu bazowego nie można przekierować, ponieważ punkt końcowy jest wbudowany w klienta. W takim przypadku należy umieścić przed nim warstwę pośredniczącą, taką jak samodzielnie hostowana bramka LiteLLM, i ponownie udostępnić model w formacie wymaganym przez klienta.

Ollama może wygenerować te konfiguracje automatycznie. ollama launch opencode uruchamia OpenCode z wbudowaną konfiguracją dla wybranego modelu, ollama launch claude wykonuje to samo dla Claude Code, a ollama launch droid --config zapisuje konfigurację bez uruchamiania narzędzia.

Instalacja Ollama i pobranie modelu obsługującego wywoływanie narzędzi

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

Instalator dodaje jednostkę systemd i uruchamia ją, więc systemctl status ollama powinno zwrócić active (running). Jeśli tak się nie dzieje, journalctl -e -u ollama wyświetli przyczynę.

Model musi obsługiwać wywoływanie narzędzi (tool calling), ponieważ jest to mechanizm działania agenta. Agent odczytuje plik, tworzy poprawkę, uruchamia test, a następnie analizuje błąd i podejmuje kolejną próbę. Model, który nie potrafi wygenerować wywołania narzędzia, opisze edycję w tekście zamiast ją wykonać, co spowoduje zapętlenie lub zatrzymanie agenta. Przed pobraniem modelu należy sprawdzić etykietę tools na jego stronie w serwisie ollama.com. Model qwen3-coder:30b posiada tę funkcjonalność, a według stanu na sierpień 2026 r. ten tag wymaga pobrania 19 GB danych i oferuje okno kontekstowe o rozmiarze 256K. Jeśli serwer korzysta wyłącznie z CPU lub ma ograniczoną ilość pamięci RAM, obliczenia zapotrzebowania na pamięć dla tagu Qwen 27B na VPS pozwolą sprawdzić, co faktycznie zmieści się w przedziale od 8 do 64 GB przed rozpoczęciem pobierania. Po pobraniu, te gigabajty zajmą miejsce na partycji głównej serwera, która w przypadku VPS zazwyczaj ma najmniej wolnej przestrzeni, dlatego warto przeczytać gdzie Ollama przechowuje pliki modeli i jak przenieść je w inne miejsce, zanim dysk zostanie zapełniony.

Teraz należy potwierdzić, jakie nazwy modeli są faktycznie obsługiwane przez serwer:

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

Ciągi znaków w tej odpowiedzi muszą zostać dokładnie, znak po znaku, uwzględnione w konfiguracji agenta. Weryfikacja tego kroku pozwala uniknąć większości błędów typu model-not-found. Jeśli Ollama nie jest jeszcze zainstalowana, szczegółowy przewodnik znajduje się w samodzielnym hostowaniu LLM za pomocą Ollama na VPS.

Skierowanie OpenCode na Ollama

Edytuj ~/.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"
        }
      }
    }
  }
}

Klucz w sekcji models to nazwa modelu przesyłana do Ollama, dlatego musi być identyczna z ollama ls. Pole name stanowi jedynie etykietę w selektorze modeli. Uruchom opencode, przełącz się na dostawcę Ollama i monitoruj journalctl -e -u ollama, aby potwierdzić, że żądanie dotarło do właściwego serwera. Konfiguracja samego agenta została opisana w uruchamianie OpenCode na VPS.

Wskazanie Claude Code na Ollama

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

Zmienna ANTHROPIC_API_KEY jest celowo ustawiona na pusty ciąg znaków. Pozostawienie rzeczywistego klucza w środowisku spowodowałoby wysyłanie żądań do hostowanego API, co skutkuje naliczeniem opłat zamiast lokalnego przetwarzania danych. Zmienna ollama launch claude konfiguruje wszystkie te parametry automatycznie.

Należy mieć świadomość ograniczeń warstwy kompatybilności. Nie implementuje ona tool_choice ani buforowania promptów (prompt caching) i nie posiada punktu końcowego do zliczania tokenów, dlatego wyświetlane liczby tokenów są przybliżeniami pochodzącymi z własnego tokenizatora modelu. Claude Code przesyła również rozbudowany prompt systemowy oraz szeroki zestaw narzędzi, co wymaga większego okna kontekstowego niż w przypadku standardowego klienta czatu. Szersze zagadnienie dotyczące tego, co jest obsługiwane, a co nie, zostało omówione w sekcji czy można hostować Claude samodzielnie.

Skierowanie Aider na Ollama

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

Dokumentacja Aider zaleca użycie prefiksu ollama_chat/ zamiast ollama/. Narzędzie pozwala również na przypisanie okna kontekstowego dla każdego modelu w .aider.model.settings.yml, co jest przydatne, gdy dany model wymaga innego rozmiaru okna niż domyślny rozmiar serwera:

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

Dlaczego działająca konfiguracja generuje bezsensowne odpowiedzi

To jest kluczowa sekcja. Ollama dobiera domyślną długość kontekstu na podstawie wykrytej pamięci VRAM (pamięć wideo na GPU), a wartości te są publicznie znane:

[
  {
    "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"
  }
]

Większość planów VPS oraz każdy serwer oparty wyłącznie na CPU mieści się w pierwszym wierszu: 4,096 tokenów. Tylko wydajne GPU otrzymuje 262,144 tokenów z ostatniego wiersza.

Agent zużywa 4096 tokenów, zanim wykona jakąkolwiek pracę. Prompt systemowy, definicje narzędzi, lista plików w repozytorium oraz pierwszy otwarty plik przekraczają już ten limit. Problem polega na tym, że system nie zgłasza błędu. Dokumentacja Aider wskazuje, że Ollama po cichu odrzuca kontekst wykraczający poza okno. Najstarsze tokeny są usuwane, więc model odpowiada pewnie na temat pliku, którego już nie widzi, lub zapomina instrukcję wydaną dwa kroki wcześniej. Ten mechanizm odpowiada za większość zgłoszeń, że lokalny model jest zbyt mało inteligentny do pisania kodu. Wybór samej wartości jest decyzją użytkownika, a lektura ile pamięci KV cache zajmuje num_ctx przy różnych rozmiarach jest zalecana przed podjęciem decyzji.

Dokumentacja Ollama wskazuje, że w zadaniach typu agenci i narzędzia programistyczne należy ustawić co najmniej 64000 tokenów. Skonfiguruj to na serwerze:

sudo systemctl edit ollama.service

Dodaj poniższe linie w pliku override:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Następnie przeładuj i zrestartuj usługę:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps służy do weryfikacji. Wyświetla kolumnę CONTEXT, która wskazuje liczbę tokenów faktycznie otrzymaną przez model. Wartości ID oraz SIZE będą się różnić:

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

Ustawienie to należy wprowadzić na serwerze, a nie w agencie, z dwóch powodów. Schemat OpenAI chat completions nie posiada pola dla długości kontekstu, więc klient kompatybilny z OpenAI nie może o nią zawnioskować. Ponadto ustawienie jest globalne dla serwera, więc każdy agent skierowany na tę maszynę je dziedziczy. Strona wyjściowa posiada własny limit i w przeciwieństwie do długości kontekstu, jest on przekazywany przez endpoint kompatybilności, dlatego num_predict oraz mapowane na nie pole max_tokens są parametrami, które należy modyfikować, gdy odpowiedź urywa się w połowie poprawki. Jeśli dany model wymaga innego okna, należy przygotować jego kopię za pomocą Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Kontekst nie jest darmowy. Większe okno zwiększa zużycie pamięci, dlatego monitoruj kolumnę PROCESSOR. 100% GPU to pożądany stan. Gdy część modelu zostanie przeniesiona do pamięci RAM procesora (CPU), szybkość generowania tokenów spada na tyle, że pętla agenta staje się bezużyteczna, a pomiar tokenów na sekundę w lokalnym LLM pozwala określić rzeczywisty limit wydajności serwera. Dobór parametrów maszyny przed zakupem opisano w ile pamięci RAM i CPU potrzebuje VPS dla agenta programistycznego.

Utrzymywanie modelu w pamięci między żądaniami

Domyślnie Ollama zwalnia model z pamięci 5 minut po ostatnim żądaniu. Jest to poprawne w przypadku czatu, lecz nieefektywne w pracy agentów. Podczas analizy różnic w kodzie (diff) licznik czasu upływa, a kolejne żądanie wymusza ponowne wczytanie dziesiątek gigabajtów wag z dysku przed wygenerowaniem pierwszego tokena. Jest to odczuwalne jako zawieszenie aplikacji.

OLLAMA_KEEP_ALIVE przyjmuje ciąg znaków określający czas, taki jak 10m lub 24h, liczbę sekund, -1 w celu utrzymania modelu w pamięci bezterminowo lub 0 w celu natychmiastowego zwolnienia zasobów. Ustaw tę wartość obok długości kontekstu:

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

Pole żądania keep_alive występuje wyłącznie w natywnych punktach końcowych /api/generate oraz /api/chat serwera Ollama, a nie w punktach końcowych zapewniających kompatybilność, dlatego agent nie może ustawić tej wartości dla każdego żądania z osobna. Zmienna środowiskowa jest jedynym dostępnym mechanizmem sterowania. Gdy konieczne jest odzyskanie pamięci, ollama stop qwen3-coder:30b zwalnia model bez zatrzymywania serwera. Jeśli ustawienie ma być trwałe po restarcie lub jeśli zachodzi potrzeba wyważenia korzyści z utrzymywania wag w pamięci przez cały dzień względem odzyskania zasobów, utrzymywanie modelu Ollama w pamięci pozwala na realizację obu tych celów.

Uruchamianie Ollama na oddzielnym serwerze

Ollama wiąże się z localhost. Aby uzyskać do niej dostęp z innej maszyny, ustaw OLLAMA_HOST=0.0.0.0:11434 w tym samym pliku override systemd i zrestartuj usługę.

Wykonuj to wyłącznie w sieci prywatnej. Dokumentacja Ollama wskazuje, że lokalne API nie wymaga uwierzytelniania, więc port 11434 otwarty na świat oznacza, że każdy może korzystać z Twojego sprzętu i odczytywać dane przesyłane przez agenta. Istnieją dwie bezpieczne opcje. Pozostaw powiązanie z localhost i przekieruj port przez SSH ze swojego laptopa:

ssh -N -L 11434:localhost:11434 you@your-vps

Twój agent nadal wskazuje na http://localhost:11434/v1 i nie wykrywa różnicy. Drugą opcją jest VPN, przy czym Ollama powinna być powiązana z adresem VPN zamiast 0.0.0.0. Jeśli z jednej maszyny ma korzystać kilka osób lub kilka agentów, pamiętaj, że scheduler Ollama nie jest przystosowany do takiego obciążenia, a porównanie Ollama i vLLM wskazuje, w którym momencie różnica w przepustowości staje się odczuwalna.

Kiedy lokalny model programistyczny wygrywa, a kiedy nie

Agent sterowany modelem hostowanym lokalnie nie zastępuje w każdym zadaniu modelu dostępnego przez API typu frontier. Wygrywa on zdecydowanie w czterech rodzajach pracy.

• Masowe, mechaniczne edycje, gdzie każda zmiana jest niewielka i możliwa do zweryfikowania. Zmiana nazw w całym repozytorium, dodawanie wskazówek typów, pisanie dokumentacji, tłumaczenie komentarzy. Model może pracować godzinami, a koszty nie rosną.
• Praca, która nie może opuścić Twojego sprzętu. Kod klienta objęty umową o zachowaniu poufności lub wewnętrzne repozytorium, którego nie wolno wysyłać do podmiotów trzecich.
• Maszyny działające w trybie offline lub air-gapped, gdzie nie ma możliwości wywołania żadnego zewnętrznego API.
• Przewidywalne koszty. Gdy serwer jest już opłacony, agent zużywający tokeny w pętli nie generuje dodatkowych opłat, co jest przeciwieństwem modelu rozliczanego przez API. Kiedy GPU VPS staje się bardziej opłacalny niż tokeny API zawiera stosowne wyliczenia.

Model lokalny przegrywa w długich, wieloetapowych zadaniach. Polecenie "znajdź przyczynę niepowodzenia testu, napraw ją, zaktualizuj wywołania" wymaga wielu poprawnych użyć narzędzi z rzędu, przy zachowaniu całej historii w kontekście. Model o rozmiarze od 8B do 14B na przeciętnym serwerze wygeneruje błędne wywołanie narzędzia lub zgubi plan po kilku krokach, przez co poświęcisz więcej czasu na jego korygowanie, niż zajęłoby wykonanie zadania ręcznie. Nie jest to problem z promptem, którego można uniknąć poprzez jego optymalizację. To kwestia wydajności modelu.

Model lokalny przegrywa również wtedy, gdy koszt błędu jest wysoki, a Ty nie zamierzasz czytać każdej linii kodu. Zlecaj modelowi lokalnemu wąskie zadania, których wynik jesteś w stanie zweryfikować, a model hostowany zachowaj do pracy, której nie chcesz sprawdzać krok po kroku.

Tryby awarii i komunikaty, które zobaczysz

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Serwer nie działa lub agent wskazuje na inny host. Uruchom systemctl status ollama, a następnie journalctl -e -u ollama.

Agent zgłasza, że model nie istnieje. Nazwa w konfiguracji nie jest zgodna z nazwą udostępnianą przez serwer. Porównaj ją z curl http://localhost:11434/v1/models i skopiuj stamtąd ciąg znaków. Tag jest częścią nazwy, więc konfiguracja wskazująca na tag, który nie został pobrany, zakończy się niepowodzeniem, nawet jeśli zainstalowany jest podobny model.

Agent odpowiada tekstem i nie edytuje pliku. Model nie obsługuje narzędzi lub żądanie wraz z definicjami narzędzi wypełniło już okno kontekstowe. Sprawdź etykietę tools na stronie modelu, a następnie sprawdź kolumnę CONTEXT w ollama ps.

Długa cisza przed pierwszym tokenem, a potem normalna prędkość. Czas podtrzymania połączenia (keep-alive) wygasł i wagi są ponownie odczytywane z dysku. Ustaw OLLAMA_KEEP_ALIVE.

Model zaprzecza plikowi, który właśnie odczytał. Nastąpiło ucięcie kontekstu. ollama ps zazwyczaj pokazuje wartość CONTEXT mniejszą, niż przypuszczasz, ponieważ zmienna środowiskowa trafiła do powłoki, a nie do jednostki systemd.

Wszystko działa, ale powoli, a PROCESSOR nie jest 100% GPU. Model wraz z kontekstem nie mieści się w VRAM. Zmniejsz długość kontekstu lub przejdź na mniejszy model bądź mniejszą kwantyzację. Zanim pobierzesz ponownie, ile pamięci zajmują poszczególne formaty q4_K_M, q8_0 oraz fp16 i gdzie faktycznie spada jakość podpowie, ile miejsca zyskasz po zmianie i co w zamian tracisz.

FAQ

Czy mogę skierować Claude Code na Ollama?

Tak, ale nie za pomocą adresu URL zgodnego z OpenAI. Claude Code korzysta z API Anthropic Messages, a Ollama udostępnia ten interfejs pod adresem /v1/messages na tym samym porcie 11434. Wyeksportuj zmienne ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama oraz pustą wartość ANTHROPIC_API_KEY, a następnie uruchom narzędzie za pomocą claude --model qwen3-coder:30b. Polecenie ollama launch claude zapisuje te ustawienia automatycznie. Warstwa kompatybilności nie implementuje tool_choice ani buforowania promptów (prompt caching) i nie posiada punktu końcowego do zliczania tokenów, dlatego raportowane wartości są przybliżone.

Dlaczego mój lokalny model odpowiada na temat kodu, którego nie widzi?

Ponieważ żądanie przestało mieścić się w oknie kontekstowym, a jego najstarsza część została usunięta bez zgłoszenia błędu. Ollama ustawia domyślny kontekst na podstawie wykrytej pamięci VRAM. Poniżej 24 GiB wartością domyślną jest 4,096 tokenów, co jest wartością przekraczaną już przez sam systemowy prompt agenta oraz definicje narzędzi. Ustaw OLLAMA_CONTEXT_LENGTH=64000 w jednostce systemd, zrestartuj Ollama i sprawdź, czy kolumna CONTEXT w ollama ps wskazuje nową wartość.

Który model uruchomić dla agenta programistycznego na VPS?

Wybierz największy model z etykietą tools, który mieści się w pamięci przy oknie kontekstowym 64k, preferując modele dostrojone pod kątem kodu. qwen3-coder:30b jest typowym wyborem na serwerze GPU z odpowiednią ilością VRAM. Jeśli ten model jest zbyt duży dla Twojego serwera, dane dotyczące pamięci RAM i prędkości działania na samym procesorze dla Nemotron 3.5 Lightning stanowią przydatne porównanie przed pobraniem plików. Poniżej około 14B parametrów model może nadal dobrze odpowiadać na pytania o kod, ale zawodzić przy wieloetapowych edycjach, ponieważ praca agenta jest wrażliwa na drobne błędy formatowania w wywołaniach narzędzi. Przetestuj rozwiązanie na jednym rzeczywistym zadaniu z własnego repozytorium, zamiast używać przykładowego promptu.

Czy potrzebuję GPU, aby uruchomić agenta programistycznego na własnym modelu?

W praktyce tak. Wnioskowanie oparte wyłącznie na CPU działa i sprawdza się w przypadku pojedynczych pytań, ale agent wysyła wiele żądań na zadanie, a każde z nich ponownie odczytuje długą historię. Niska prędkość generowania tokenów sprawia, że dwuminutowe zadanie trwa godzinę. Sprawdź kolumnę PROCESSOR w ollama ps: każda wartość inna niż 100% GPU oznacza, że część modelu działa na procesorze, co drastycznie obniża tempo generowania tokenów.