Jak połączyć Ollama z agentem programistycznym

Konfiguracja 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 lokalny serwer ją ignoruje, więc można wprowadzić 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 jeden z tych dwóch formató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 przydzielania modelowi zadań, do których jest przystosowany. Obie kwestie zostały omówione w osobnych sekcjach, a rzeczywiste ograniczenia przedstawiono na końcu.

Które agenty programistyczne 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łasną obsługę Ollama oddzielnie. Obejmuje to większość narzędzi określanych mianem agentów programistycznych w sierpniu 2026 roku. Nie wszystkie korzystają z tego samego formatu 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/v1 oraz dowolny niepusty ciąg znaków jako klucz API.
• Claude Code w ogóle nie akceptuje adresu bazowego OpenAI. Obsługuje on 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łania 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ę błędu.

Model musi obsługiwać wywołania 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 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 posiada ograniczoną ilość pamięci RAM, obliczenia zapotrzebowania na pamięć dla tagu Qwen 27B na VPS pozwolą ustalić, co faktycznie zmieści się w przedziale od 8 do 64 GB przed rozpoczęciem pobierania.

Teraz należy potwierdzić, jakie nazwy modeli są faktycznie udostępniane przez serwer:

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

Ciągi znaków w tej odpowiedzi muszą zostać dokładnie, znak po znaku, odwzorowane w konfiguracji agenta. Weryfikacja tego kroku eliminuje większość 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 models to nazwa modelu wysył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 Ollama w Claude Code

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

ANTHROPIC_API_KEY celowo pozostawiono jako pusty ciąg znaków. Rzeczywisty klucz pozostawiony w środowisku spowodowałby wysyłanie żądań do hostowanego API, co wiążełoby się z naliczeniem opłat i brakiem lokalnego wnioskowania. 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 korzysta również z rozbudowanego promptu systemowego oraz szerokiego zestawu narzędzi, przez co wymaga większego kontekstu niż standardowy klient czatu. Szersze zagadnienie dotyczące tego, co jest obsługiwane, a co nie, zostało omówione w czy można samodzielnie hostować Claude.

Wskazanie Ollama w Aider

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 innej wielkości okna niż domyślna wartość serwera:

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

Dlaczego działająca konfiguracja nadal generuje bezsensowne odpowiedzi

To jest kluczowa sekcja. Ollama wybiera domyślną długość kontekstu na podstawie dostępnej pamięci VRAM (pamięci 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 działający wyłącznie na CPU mieści się w pierwszym wierszu: 4,096 tokenów. Tylko wydajne GPU pozwala na użycie 262,144 tokenów z ostatniego wiersza.

Agent zużywa 4096 tokenów, zanim podejmie jakiekolwiek działanie. Prompt systemowy, definicje narzędzi, lista plików w repozytorium oraz pierwszy otwarty plik przekraczają ten limit. Problem polega na tym, że system nie zgłasza żadnego 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ę podaną dwa kroki wcześniej. Ten mechanizm jest przyczyną większości zgłoszeń, że lokalny model jest zbyt mało inteligentny do pisania kodu.

Dokumentacja Ollama zaleca, aby w zadaniach takich jak agenci czy narzędzia programistyczne ustawiać co najmniej 64000 tokenów. Należy to skonfigurować na serwerze:

sudo systemctl edit ollama.service

Dodaj 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 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 to obowiązuje dla całego serwera, więc każdy agent skierowany na tę maszynę je dziedziczy. 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 wymaga więcej pamięci, dlatego należy monitorować kolumnę PROCESSOR. Wartość 100% GPU jest pożądana. 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 liczby 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 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 wczytanie dziesiątek gigabajtów wag z dysku przed wygenerowaniem pierwszego tokena. Jest to odczuwalne jako zawieszenie aplikacji.

OLLAMA_KEEP_ALIVE przyjmuje ciąg 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 ten 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 wyłącznie w natywnych punktach końcowych /api/generate oraz /api/chat serwera Ollama, a nie w punktach zgodności, dlatego agent nie może ustawić go dla pojedynczego żądania. Zmienna środowiskowa jest jedynym dostępnym mechanizmem sterowania. Gdy konieczne jest odzyskanie pamięci, ollama stop qwen3-coder:30b zwalnia model bez zatrzymywania serwera.

Uruchamianie Ollama na oddzielnym serwerze

Ollama wiąże się z adresem 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 i odczytywać dane przesyłane przez agenta. Istnieją dwie bezpieczne opcje. Pozostawienie powiązania z localhost i przekierowanie portu przez SSH z laptopa:

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

Agent nadal wskazuje na http://localhost:11434/v1 i nie wykrywa różnicy. Drugą opcją jest VPN, przy czym Ollama jest powiązana z adresem VPN zamiast 0.0.0.0. Jeśli z jednej maszyny ma korzystać kilka osób lub kilka agentów, należy pamiętać, że harmonogram 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 API klasy frontier. Wygrywa on zdecydowanie w czterech rodzajach pracy.

• Masowe edycje mechaniczne, 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 koszt pozostaje zerowy.
• Praca, która nie może opuścić Twojego sprzętu. Kod klienta objęty umową o poufności lub wewnętrzne repozytorium, którego nie wolno przesyłać podmiotom trzecim.
• Maszyny działające w trybie offline lub w izolacji (air-gapped), gdzie nie ma dostępu do żadnego zewnętrznego API.
• Przewidywalność kosztów. Po opłaceniu serwera agent, który zużywa tokeny w pętli, nie generuje dodatkowych kosztów, co jest przeciwieństwem rozliczanego API. Kiedy serwer GPU VPS staje się bardziej opłacalny niż tokeny API zawiera stosowne wyliczenia.

Lokalny model przegrywa w przypadku długich, wieloetapowych zadań. Polecenie typu „znajdź przyczynę niepowodzenia testu, napraw ją, zaktualizuj wywołania” wymaga wielu poprawnych wywołań narzędzi z rzędu, przy zachowaniu pełnej historii w kontekście. Model o rozmiarze od 8B do 14B parametrów 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 korygowanie jego pracy, 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.

Lokalny model przegrywa również wtedy, gdy koszt błędu jest wysoki, a Ty nie zamierzasz weryfikować każdej linii kodu. Zlecaj lokalnemu modelowi wąskie zadania, których wynik sprawdzisz, a do pracy, której nie chcesz weryfikować krok po kroku, używaj modelu hostowanego.

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 jest zgodna 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ę niepowodzeniem, 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, a potem normalna prędkość. Czas podtrzymania (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ż zakładałeś, ponieważ zmienna środowiskowa została przekazana 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ę.

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 format pod adresem /v1/messages na tym samym porcie 11434. Wyeksportuj ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama oraz pustą zmienną ANTHROPIC_API_KEY, a następnie uruchom narzędzie za pomocą claude --model qwen3-coder:30b. Polecenie 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, dlatego raportowane liczby tokenów 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 prompt systemowy agenta i 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 powszechnym wyborem na serwerze GPU z wystarczającą ilością pamięci VRAM. Poniżej około 14B parametrów model może 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 model 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 jest wystarczające 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: każda wartość inna niż 100% GPU oznacza, że część modelu działa na CPU, co drastycznie obniża tempo generowania tokenów.