Jak skonfigurować Ollama z agentem programistycznym
Dowiedz się, jak połączyć agenta z lokalnym modelem poprzez base URL. Wyjaśniamy, dlaczego klucz API jest ignorowany, jak ustawić limit kontekstu i kiedy lokalne LLM wygrywają.
Co jest przedmiotem połączenia
Ollama może współpracować z agentem programistycznym, a proces łączenia jest prostszy, niż się powszechnie uważa. Wymagana jest jedynie zmiana adresu base URL oraz wybór nazwy modelu. Pole API key nadal wymaga podania wartości, jednak serwer lokalny ją ignoruje, więc można wpisać dowolny ciąg znaków.
Ollama nasłuchuje na porcie 11434 i jednocześnie udostępnia trzy interfejsy API. /api to natywne API Ollama. /v1 to warstwa zgodna z OpenAI, która obejmuje kilka formatów: /v1/chat/completions, /v1/responses, /v1/completions, /v1/models oraz /v1/embeddings. Dokumentacja Ollama wskazuje, że klucz jest w tym miejscu wymagany, lecz nie jest weryfikowany. Trzeci interfejs jest zgodny z Anthropic: klient przyjmuje http://localhost:11434 jako base URL i dodaje /v1/messages, co jest standardem obsługiwanym przez Claude Code. Większość agentów korzysta z /v1/chat/completions, Codex używa /v1/responses, a Claude Code wykorzystuje /v1/messages. Agent obsługuje już jeden z tych standardów, więc żadne inne zmiany w jego konfiguracji nie są konieczne.
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 oddzielnie. Obejmuje to większość narzędzi określanych mianem agentów programistycznych w październiku 2026 roku. Nie wszystkie obsługują ten sam format komunikacji i to właśnie te różnice 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/v1oraz dowolny niepusty ciąg znaków jako klucz API. - Claude Code w ogóle nie akceptuje adresu bazowego OpenAI. Obsługuje Anthropic Messages API, więc wymaga ustawienia
ANTHROPIC_BASE_URLnahttp://localhost:11434, gdzie Ollama udostępnia/v1/messages. - Codex korzysta z OpenAI Responses API. 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. Jeśli agent akceptuje niestandardowy adres URL, ale wymaga innego formatu API, należy umieścić przed nim warstwę tłumaczącą, taką jak samodzielnie hostowana bramka LiteLLM, i ponownie udostępnić model w formacie wymaganym przez klienta.
Ollama potrafi 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 lsInstalator 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ę błędu.
Model musi wspierać 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 pracy agenta. Przed pobraniem modelu na stronie ollama.com należy sprawdzić, czy posiada on etykietę tools. Model qwen3-coder:30b ją posiada, a według stanu na październik 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 posiada ograniczoną ilość pamięci RAM, obliczenia zapotrzebowania na pamięć dla tagu Qwen 27B na VPS pozwolą ocenić, 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 na VPS-ach zazwyczaj ma najmniej wolnej przestrzeni, dlatego warto zapoznać się z informacją gdzie Ollama przechowuje pliki modeli i jak przenieść je w inne miejsce, zanim dysk zostanie zapełniony.
Teraz należy potwierdzić, jakie nazwy modeli serwer faktycznie udostępnia:
curl http://localhost:11434/v1/modelsCiągi znaków w tej odpowiedzi muszą zostać dokładnie, znak po znaku, odwzorowane 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:30bANTHROPIC_API_KEY jest celowo ustawione na pusty ciąg znaków. Bazowy URL określa miejsce wysyłania żądań; wyczyszczenie tego klucza zapobiega przesyłaniu poświadczeń z hostowanych usług do tej lokalnej konfiguracji. ollama launch claude automatyzuje cały ten proces.
Należy znać ograniczenia warstwy kompatybilności. Nie implementuje ona tool_choice ani buforowania promptów i nie posiada punktu końcowego do zliczania tokenów, dlatego wyświetlane liczby tokenów są przybliżeniami pochodzącymi z własnego tokenizera modelu. Claude Code dostarcza również rozbudowany prompt systemowy oraz szeroki zestaw narzędzi, przez co wymaga większego kontekstu niż standardowy klient czatu. Szersze zagadnienie dotyczące tego, co jest przenoszone, a co nie, zostało omówione w czy można samodzielnie hostować Claude.
Skierowanie Aider na Ollama
export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30bDokumentacja Aider zaleca użycie prefiksu ollama_chat/ zamiast ollama/. Domyślnie Aider żąda wystarczającej ilości kontekstu dla każdego zapytania oraz dodatkowych 8k tokenów na odpowiedź. Narzędzie pozwala również na przypisanie okna kontekstu dla każdego modelu w .aider.model.settings.yml, co jest przydatne, gdy dany model wymaga innego okna niż domyślne ustawienia serwera:
- name: ollama_chat/qwen3-coder:30b
extra_params:
num_ctx: 65536Dlaczego działająca konfiguracja nadal generuje bezsensowne odpowiedzi
To jest kluczowa sekcja. Ollama wybiera domyślną długość kontekstu na podstawie całkowitej pamięci VRAM (pamięci wideo na GPU), którą wykrywa, odejmując OLLAMA_GPU_OVERHEAD dla każdego rozpoznanego układu GPU. Implementacja stosuje następujące progi:
Dane, na których opiera się ten wykres
[
{
"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"
}
]Większość planów VPS oraz wszystkie serwery oparte wyłącznie na CPU trafiają do pierwszego wiersza: 4,096 tokenów. Wiele mniejszych jednostek GPU może łącznie osiągnąć próg 47 GiB dla 262,144 tokenów w ostatnim wierszu.
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 zajmują już więcej miejsca. Problem polega na tym, że system nie zgłasza błędów. Dokumentacja Aider wskazuje, że Ollama po cichu odrzuca kontekst przekraczający okno. Najstarsze tokeny są usuwane, więc model pewnie wypowiada się na temat pliku, którego już nie widzi, lub zapomina instrukcję podaną dwa kroki wcześniej. Ten mechanizm odpowiada za większość zgłoszeń, że lokalny model jest zbyt mało inteligentny, aby pisać kod. 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 podaje, że w zadaniach takich jak agenci czy narzędzia programistyczne należy ustawić co najmniej 64000 tokenów. Należy to skonfigurować na serwerze:
sudo systemctl edit ollama.serviceDodaj te 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 psPo restarcie wyślij żądanie z agenta, a następnie uruchom ponownie ollama ps, aby załadować model do inspekcji. ollama ps służy do weryfikacji. Wyświetla ono kolumnę CONTEXT, a ta liczba oznacza wartość, którą model faktycznie otrzymał. Wartości ID oraz SIZE będą się różnić:
NAME ID SIZE PROCESSOR CONTEXT RUNNER UNTIL
qwen3-coder:30b a1b2c3d4e5f6 24 GB 100% GPU 64000 ggml 4 minutes from nowKonfigurację należy ustawić 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ą poprosić. Ponadto domyślne ustawienie serwera ma zastosowanie do każdego agenta, chyba że model lub żądanie narzuci inne. Strona wyjściowa ma własny limit i w przeciwieństwie do długości kontekstu, jest ona przesyłana przez endpoint kompatybilności, więc num_predict oraz pole max_tokens, które na nie mapuje są parametrami, które należy dostosować, gdy odpowiedź urywa się w połowie poprawki. Jeśli dany model wymaga innego okna, należy je zdefiniować w kopii za pomocą Modelfile:
FROM qwen3-coder:30b
PARAMETER num_ctx 65536ollama create qwen3-coder-64k -f ModelfileKontekst nie jest darmowy. Większe okno kosztuje więcej pamięci, więc należy monitorować kolumnę PROCESSOR. 100% GPU to wartość docelowa. 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 mierzenie liczby tokenów na sekundę w lokalnym LLM pozwala określić rzeczywisty limit dla danej maszyny. Dobór parametrów serwera przed zakupem został opisany w ile pamięci RAM i mocy CPU potrzebuje VPS dla agenta programistycznego.
Utrzymywanie modelu w pamięci między żądaniami
Domyślnie Ollama zwalnia model z pamięci po 5 minutach od ostatniego żądania. Jest to poprawne w przypadku czatu, lecz nieefektywne w pracy agentów. Przerwa na analizę diffa powoduje upłynięcie czasu, a kolejne żądanie wymusza ponowne wczytanie dziesiątek gigabajtów wag z dysku przed wygenerowaniem pierwszego tokena. Jest to odczuwalne jako zawieszenie systemu.
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. Parametr należy ustawić obok długości kontekstu:
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"Pole żądania keep_alive występuje w natywnych punktach końcowych /api/generate i /api/chat serwera Ollama oraz jako rozszerzenie Ollama w /v1/chat/completions. Agent obsługujący dodatkowe pola żądania może przesłać je w tym miejscu; w przeciwnym razie należy użyć zmiennej środowiskowej. 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 między utrzymywaniem wag w pamięci przez cały dzień a odzyskaniem 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, należy ustawić OLLAMA_HOST=0.0.0.0:11434 w tym samym pliku override systemd i zrestartować usługę.
Należy to robić 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. 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-vpsTwó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, Ollama obsługuje żądania równoległe, o ile pozwala na to pamięć, a porównanie Ollama i vLLM wskazuje, przy jakim obciążeniu 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 jest skierowany 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 zgadza się z nazwą udostępnianą przez serwer. Porównaj ją z curl http://localhost:11434/v1/models i skopiuj stamtąd odpowiedni ciąg znaków. Tag jest częścią nazwy, więc konfiguracja wskazująca na tag, który nie został pobrany, zakończy się błędem, nawet jeśli zainstalowano 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, 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 przed chwilą odczytał. Nastąpiło ucięcie kontekstu. ollama ps zazwyczaj pokazuje wartość CONTEXT mniejszą niż zakładano, ponieważ zmienna środowiskowa została przekazana do powłoki, a nie do jednostki systemd.
Wszystko działa, ale wolno, a PROCESSOR pokazuje 100% CPU lub podział CPU/GPU. Zazwyczaj model wraz z kontekstem nie mieści się w pamięci VRAM. Jeśli PROCESSOR wskazuje 100% CPU na maszynie z GPU, najpierw wyklucz inną przyczynę: Ollama mogła w ogóle nie wykryć GPU. Dokumentacja Ollama wskazuje, że w systemie Linux po cyklu uśpienia/wznowienia czasami nie udaje się wykryć GPU NVIDIA i następuje powrót do CPU, a przeładowanie sterownika za pomocą sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm rozwiązuje ten problem. Jeśli GPU zostało wykryte, a podział nadal występuje, zmniejsz długość kontekstu lub przejdź na mniejszy model bądź mniejszą kwantyzację. Przed ponownym pobraniem, ile pamięci zajmują poszczególne formaty q4_K_M, q8_0 oraz fp16 i gdzie faktycznie spada jakość informuje, ile miejsca zyskuje się po zmianie na niższy poziom i co się przy tym traci. Unknown jest również możliwą wartością PROCESSOR; nie powoduje ona odciążenia procesora (CPU offloading).
FAQ
Czy mogę skierować Claude Code na Ollama?
Tak, ale nie za pomocą adresu URL zgodnego z OpenAI. Claude Code korzysta z Anthropic Messages API, a Ollama udostępnia ten interfejs pod adresem /v1/messages na tym samym porcie 11434. Wyeksportuj 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. ollama launch claude zapisuje te same ustawienia automatycznie. Warstwa kompatybilności nie implementuje tool_choice ani buforowania promptów i nie posiada punktu końcowego do zliczania tokenów, więc raportowane liczby 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 ustala domyślny kontekst na podstawie całkowitej wykrytej pamięci VRAM po odjęciu skonfigurowanego narzutu na każdy GPU: poniżej 23 GiB domyślną wartością jest 4,096 tokenów, od 23 do poniżej 47 GiB jest to 32,768 tokenów, a przy 47 GiB lub więcej jest to 262,144 tokenów. Ustaw OLLAMA_CONTEXT_LENGTH=64000 w jednostce systemd, zrestartuj Ollama i potwierdź, że kolumna CONTEXT w ollama ps wskazuje nową wartość.
Który model wybrać 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 powszechnym wyborem na serwerze GPU z wystarczającą ilością VRAM. Jeśli ten tag jest zbyt duży dla Twojego serwera, dane dotyczące pamięci RAM i prędkości dla samego CPU dla Nemotron 3.5 Lightning stanowią przydatne porównanie przed rozpoczęciem pobierania. 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 nie wybacza drobnych błędów formatowania w wywołaniach narzędzi. Przeprowadź test 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. Inferencja oparta wyłącznie na CPU działa i jest wystarczająca do 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 wydłuża się do godziny. Sprawdź kolumnę PROCESSOR w ollama ps: 100% CPU lub podział CPU/GPU wskazuje na użycie CPU, co spowalnia inferencję. Unknown nie ustanawia odciążenia CPU.