Claude Code mit einem lokalen Ollama-Modell nutzen und zurück zur Cloud wechseln

Claude Code kann über Ollamas Anthropic-kompatible API ein lokales Modell verwenden. Eine normale Chat-Antwort beweist jedoch nicht, dass das Modell für einen Coding-Agenten geeignet ist. Vor produktiver Arbeit zählen drei Bedingungen: Das Modell muss Tool-Aufrufe unterstützen, der Rechner mindestens 64k Kontext tragen können und die Aufgabe muss so klar begrenzt sein, dass sie sich mit Befehlen und einem Diff prüfen lässt.

Diese Anleitung hält den Wechsel reversibel. Du verbindest Claude Code über den offiziellen Ollama-Weg mit qwen3.5, führst einen Abnahmetest an einer Datei durch, prüfst den tatsächlichen Ausführungsort, klärst API- und Datengrenzen und entfernst danach die lokale Umleitung, bevor du zur Cloud zurückkehrst. Die Befehle verwenden Bash unter macOS, Linux oder WSL. Sie sind Schritte zum eigenen Ausführen, keine Behauptung, dass dieser Artikel den Test auf deiner Hardware durchgeführt hat.

Zuerst entscheiden: lokal, Cloud oder ein hybrider Ablauf

Lokale Modelle eignen sich vor allem für klar abgegrenzte Aufgaben mit mechanisch prüfbarem Ergebnis. Ein großes Repository, eine serviceübergreifende Migration oder schwierige Fehlersuche profitieren meist stärker von einem Cloud-Modell als von einem kleinen lokalen Modell mit erheblichem CPU-Offload.

Arbeitslast	Empfohlener Start	Warum
Korrektur in einer Datei, ein neuer Test oder Erklärung einer lokalen Funktion	Zuerst lokal testen	Begrenzter Kontext, Ergebnis per Befehl und Diff prüfbar
Kleines oder mittleres Modul mit klaren Abhängigkeiten	Lokal oder hybrid	Erst Smoke-Test bestehen, dann Umfang schrittweise erhöhen
Großes Monorepo, serviceübergreifendes Refactoring oder komplexe Analyse	Zuerst Cloud	Mehr effektiver Kontext und zuverlässigere Tool-Planung nötig
Das Modell hält 64k nur mit starkem CPU-Offload	Zuerst Cloud	Latenz und Hänger nehmen dem lokalen Weg den praktischen Vorteil
Der Ablauf braucht Prompt Caching, Batches API, PDF-Blöcke oder exakte Token-Zählung	Zuerst Cloud	Ollama implementiert derzeit nur einen Teil der Anthropic Messages API
Quellcode darf nicht an ein Remote-Modell gehen	Lokal, Cloud-Funktionen deaktivieren	Web-Tools, MCP-Server und Shell-Befehle müssen trotzdem separat geprüft werden

Eine sinnvolle Hybridregel: kleine, wiederholbar prüfbare Änderungen lokal ausführen und für repositoryweites Denken, nicht unterstützte API-Funktionen oder wiederholte lokale Fehler ausdrücklich zur Cloud wechseln. So bleibt die Claude-Code-Oberfläche gleich, ohne beide Backends als gleichwertig darzustellen.

Schritt 1: Tool-fähiges Modell wählen und 64k Kontext bereitstellen

Claude Code braucht mehr als Textgenerierung. Das Modell muss zuverlässig Tool-Aufrufe erzeugen, damit der Client Dateien lesen, Änderungen anwenden und Befehle ausführen kann. Die Qwen3.5-Seite bei Ollama nennt tools als Fähigkeit und zeigt einen Claude-Code-Startbefehl. Das konkret geladene Modell lässt sich zusätzlich über Ollamas Model-Details-API prüfen.

Lade das Modell und untersuche capabilities:

ollama pull qwen3.5

curl http://localhost:11434/api/show \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.5"}'

Prüfe vor dem nächsten Schritt, dass capabilities den Eintrag tools enthält. Fehlt er, ersetzt eine normale Chat-Antwort keine Agentenprüfung. Wähle ein in der aktuellen Ollama-Bibliothek ausdrücklich als Tool-fähig gekennzeichnetes Modell, lade es und wiederhole die Kontrolle.

Der zweite Engpass ist der Kontext. Ollamas Dokumentation zur Kontextlänge empfiehlt für Websuche, Agenten und Coding-Tools mindestens 64.000 Tokens und weist darauf hin, dass größerer Kontext mehr Speicher benötigt. Stelle in der Ollama-App context length auf 64000 oder höher. Bei einem aus der Shell gestarteten Dienst stoppst du zuerst die laufende Instanz und startest in einem eigenen Terminal:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Lass dieses Terminal offen. Warte auf den Serverstart und arbeite in einem zweiten Terminal weiter. Ist der Port bereits belegt, läuft schon eine Ollama-Instanz; ändere deren Kontextkonfiguration, statt einen zweiten Server zu starten.

Schritt 2: Claude Code über Ollamas offizielle Integration starten

Der kürzeste offizielle Weg lautet:

ollama launch claude --model qwen3.5

Damit lässt sich die Integration am einfachsten herstellen. Führe nach dem Start in Claude Code /status aus und notiere die aktiven Settings-Quellen. Diese Information hilft später, falls eine persistente Ebene den Client weiterhin zu Ollama umleitet, obwohl du zur Cloud zurückkehren möchtest.

Soll die Änderung nur für das aktuelle Terminal gelten, setze die Variablen manuell. Auch das folgende Beispiel ist Bash:

read -rs ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL="http://localhost:11434"
claude --model qwen3.5

read -rs nimmt die Eingabe an, ohne sie anzuzeigen. Gib ollama ein und drücke Enter. Ollamas kompatibler Endpoint verlangt die Authentifizierungsvariable, der lokale Server prüft ihren Wert jedoch nicht. ANTHROPIC_BASE_URL leitet Modellaufrufe an den lokalen Endpoint, während --model qwen3.5 das Testmodell eindeutig festlegt und das Ergebnis nicht von einem alten ANTHROPIC_MODEL oder gespeicherten Standard abhängen lässt.

Schritt 3: Lesen, Bearbeiten und Befehle an einer Datei prüfen

Nutze nicht gleich ein produktives Repository als ersten Test. Lege ein isoliertes Verzeichnis an, in dem jedes Ergebnis über Datei, Exit-Code und Diff sichtbar ist.

mkdir -p claude-ollama-smoke
cd claude-ollama-smoke
git init
cat > total.py <<'PY'
def total(values):
    return sum(values)

if __name__ == "__main__":
    assert total([2, 3]) == 5
PY
git add total.py
python3 total.py

python3 total.py sollte ohne Ausgabe mit Code 0 enden. Starte Claude Code lokal aus diesem Verzeichnis und sende folgende Aufgabe:

Ändere ausschließlich total.py.
Wenn ein Element in values weder int noch float ist, soll total einen TypeError mit der exakten Meldung numbers only auslösen.
Füge in __main__ eine Prüfung für [2, "3"] hinzu, die denselben TypeError und dieselbe Meldung bestätigt.
Führe python3 total.py aus.
Ändere keine andere Datei. Zeige am Ende den Diff.

Die Aufgabe ist bewusst klein, deckt aber die zentrale Agentenschleife ab: Datei lesen, Änderung planen, Bearbeitungswerkzeug aufrufen, Bash-Befehl anfordern, Ergebnis beobachten und den finalen Unterschied zeigen. Lass die Berechtigungsabfragen von Claude Code aktiviert. Ein lokales Modell macht eine uneingeschränkte Shell nicht sicher.

Führe danach selbst aus:

python3 total.py
git status --short
git diff -- total.py
ollama ps

Abnahmekriterien:

1. python3 total.py endet mit Code 0.
2. git status --short nennt nur total.py, und git diff -- total.py enthält ausschließlich die geforderte Typprüfung und Assertion.
3. Im Claude-Code-Verlauf sind Datei- und Bash-Tool-Aufrufe oder Berechtigungsabfragen sichtbar, nicht nur ein Codevorschlag als Text.
4. Während der Aufgabe listet ollama ps qwen3.5, CONTEXT ist mindestens 64000, und PROCESSOR zeigt vollständige GPU-Nutzung, teilweisen Offload oder überwiegende CPU-Nutzung.

Schlägt ein Punkt fehl, vergrößere den Umfang noch nicht auf ein echtes Repository. Behebe zuerst die Ursache und entscheide dann zwischen anderem Modell, kleinerer Aufgabe und Cloud.

Schritt 4: Ausführungsgrenze prüfen, nicht nur die localhost-URL

ANTHROPIC_BASE_URL=http://localhost:11434 zeigt, dass Claude Code Modellaufrufe an einen lokalen Port sendet, beweist aber nicht, dass der gesamte Ablauf offline ist. Stärkere Indizien sind ein Modell-Tag ohne :cloud, das Modell während der Aufgabe in ollama ps sowie lokale PROCESSOR- und CONTEXT-Werte, die zur Zuweisung des Rechners passen.

Ollamas FAQ erklärt, dass Ollama Prompts und Daten bei lokalem Betrieb nicht sieht, während Prompts und Antworten cloudgehosteter Modelle vom Cloud-Dienst verarbeitet werden. Die aktuelle Qwen3.5-Seite startet Claude Code mit dem lokalen Tag qwen3.5. Leite den Namen eines Cloud-Modells nicht durch Anhängen eines Suffixes an einen lokalen Tag ab; verwende zur Prüfung dieser Grenze einen Tag, der im aktuellen offiziellen Cloud-Katalog oder Integrationsleitfaden ausdrücklich genannt wird, etwa gemma4:cloud. Bestimme den Ausführungsort anhand eines gültigen Tags, ollama ps und der lokalen Ressourcenzuweisung.

Prüfe andere Netzwerkwege getrennt:

• Ein über Bash gestarteter Befehl kann auf das Netzwerk zugreifen, Dateien hochladen oder ein anderes CLI aufrufen.
• Ein MCP-Server besitzt einen eigenen Prozess, eigene Rechte und einen eigenen Datenpfad.
• Websuche, Web Fetch und Ollama-Cloud-Modelle sind keine lokale Inferenz.
• Repository-Hooks, Testskripte und Paketmanager können ebenfalls externe Dienste kontaktieren.

Für einen strengeren lokalen Ollama-Modus ergänze den folgenden Schlüssel in der vorhandenen Datei ~/.ollama/server.json, ohne andere Einstellungen zu löschen:

{
  "disable_ollama_cloud": true
}

Starte Ollama neu und prüfe die Logs auf Ollama cloud disabled: true. Laut Ollama werden damit Cloud-Modelle und Websuche deaktiviert. Andere Netzwerkzugriffe von Claude Code, MCP-Servern oder Shell-Befehlen werden dadurch nicht geprüft.

Schritt 5: Grenzen der Kompatibilität verstehen

Ollama stellt eine Kompatibilitätsschicht für die Anthropic Messages API bereit, keine vollständige Neuimplementierung der Anthropic API. Die aktuelle Dokumentation nennt Messages, Streaming, System Prompts, Bilder, Tool Calls, Tool Results und Thinking als unterstützte Fähigkeiten. Das reicht für die grundlegende Claude-Code-Agentenschleife.

Protokollkompatibilität bedeutet keine Verhaltensgleichheit. Qualität der Tool-Auswahl, Genauigkeit des Patches, Stabilität langer Aufgaben und Befolgung von Anweisungen hängen von Modell, Quantisierung, Kontextzuweisung und Hardware ab. Ein bestandener Ein-Datei-Test zeigt, dass der minimale Weg in deiner Umgebung funktioniert; er beweist keine Gleichwertigkeit mit einem Cloud-Claude-Modell in einem großen Repository.

Ollama führt derzeit /v1/messages/count_tokens, Prompt Caching, Batches API, Citations, PDF-document-Blöcke und serverseitig gesendete Streaming-Fehler als nicht unterstützt auf. Token-Zahlen werden außerdem als Näherungen auf Basis des Modell-Tokenizers beschrieben. Wenn dein Ablauf eine dieser Funktionen benötigt, halte den Cloud-Weg bereit, statt die Lücke mitten in der Aufgabe zu entdecken.

Schritt 6: ausdrücklich zur Cloud zurückwechseln

Existieren die lokalen Variablen nur in der aktuellen Bash-Sitzung, beende Claude Code und führe aus:

unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY ANTHROPIC_MODEL ANTHROPIC_DEFAULT_HAIKU_MODEL ANTHROPIC_DEFAULT_SONNET_MODEL ANTHROPIC_DEFAULT_OPUS_MODEL
claude

Der neue Prozess kann wieder der normalen Anmeldung oder deiner Cloud-Provider-Konfiguration folgen. Prüfe nach dem Start /status und stelle eine kleine Nur-Lese-Frage. Ein erfolgreich gestarteter Client beweist noch keine abgeschlossene Cloud-Anfrage.

Erreicht Claude Code weiterhin Ollama, liegt die Umleitung wahrscheinlich in Settings statt in der aktuellen Shell. Die offizielle Claude-Code-Referenz erklärt, dass ein env-Wert in einer Settings-Datei die gleichnamige Shell-Variable überschreibt. Ermittle mit /status die aktiven Quellen und entferne lokale Werte für ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY sowie Modell-Overrides aus der zutreffenden Ebene:

• ~/.claude/settings.json
• .claude/settings.json
• .claude/settings.local.json
• zentral verwaltete Organisations-Settings

Beende Claude Code vollständig und starte es nach der Änderung neu. Ein verwalteter Wert lässt sich nicht durch eine niedrigere Ebene aufheben; dafür ist eine Änderung durch den Administrator nötig.

Wenn das lokale Modell ungeeignet ist, du aber im selben Claude Code eine Anthropic-kompatible Cloud-API nutzen möchtest, folge der aktuellen BetterToken-Anleitung für Claude Code. Der aktuelle Base URL lautet https://bettertoken.ai: ohne www und ohne /v1. Kopiere zuerst die exakte Model ID aus der model plaza. Die aktuelle manuelle Konfiguration verwendet ANTHROPIC_MODEL für das Hauptmodell und die drei Variablen ANTHROPIC_DEFAULT_*_MODEL für die Aliase Haiku, Sonnet und Opus. Für einen kontrollierten Smoke-Test können zunächst alle vier Variablen auf dieselbe exakte ID zeigen. Diese temporäre Bash-Sitzung schreibt den API Key nicht in die Befehlshistorie:

read -rsp "BetterToken API Key: " ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
read -rp $'\nBetterToken Model ID: ' ANTHROPIC_MODEL
export ANTHROPIC_MODEL
export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
export API_TIMEOUT_MS="3000000"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"
claude

Die erste Abfrage blendet die Eingabe des API Keys aus; bei der zweiten fügst du die exakte Model ID aus der model plaza ein. Dieser Smoke-Test verweist das Hauptmodell und alle drei Aliase auf dieselbe ID. Wenn du bewusst unterschiedliche Modelle je Rolle verwendest, setze jede Default-Variable auf ihre jeweilige exakte ID. Hänge /v1 nicht an den Base URL an. Beende Claude Code nach Änderungen an dauerhaften Settings vollständig und starte es neu; auch bei einer temporären Sitzung muss der alte Prozess vor diesem Block geschlossen sein. Sende anschließend eine kurze Nur-Lese-Anfrage. Der Wechsel gilt erst als bestätigt, wenn eine normale Antwort ohne 401-, Verbindungs- oder Modellfehler kommt und /status die erwartete aktive Quelle zeigt; vollständige Funktionsgleichheit zwischen lokalem und Cloud-Weg folgt daraus nicht.

Häufige Fehler systematisch prüfen

ConnectionRefused oder keine Antwort von localhost:11434

Prüfe, ob der Ollama-Prozess läuft und der Endpoint den erwarteten Port verwendet. Starte ihn bei Bedarf mit ollama serve. Ist der Port belegt, finde die vorhandene Instanz, statt eine zweite zu starten. Vergewissere dich vor dem Neustart von Claude Code, dass curl http://localhost:11434/api/ps JSON zurückgibt.

Chat funktioniert, aber Claude Code liest oder bearbeitet keine Dateien

Rufe /api/show erneut auf und bestätige, dass das Modell tools meldet. Achte anschließend auf Berechtigungsabfragen von Claude Code. Schreibt das Modell nur „Du könntest den Code so ändern“, ohne einen Tool Call zu erzeugen, wechsle zu einem ausdrücklich Tool-fähigen Modell. Ein unterstütztes Tool-Feld belegt den Transport, nicht zuverlässige Tool-Planung jedes Modells.

Die Sitzung ist extrem langsam oder verliert bei längeren Aufgaben Kontext

Führe ollama ps aus und prüfe PROCESSOR und CONTEXT. Starker CPU-Offload, weniger als 64k Kontext oder wiederholter Speicherdruck sind Gründe, die Aufgabe zu verkleinern, ein kleineres Tool-fähiges Modell zu wählen oder die Cloud zu nutzen. Entferne nicht Berechtigungen und Prüfungen, nur damit die Interaktion schneller wirkt.

Änderungen in der Shell ändern Endpoint oder Modell nicht

Führe /status in Claude Code aus. Ein env-Wert aus Settings kann den Shell-Wert ersetzen, während --model und /model Vorrang vor ANTHROPIC_MODEL haben. Bereinige die tatsächlich wirksame Quelle, starte vollständig neu und wiederhole eine Nur-Lese-Anfrage.

Die praktische Entscheidungsregel

Behandle lokales Claude Code als Ausführungsweg, der sich einen größeren Umfang erst verdienen muss, nicht als einfachen Schalter. Bestätige tools, weise mindestens 64k Kontext zu und prüfe mit der Ein-Datei-Aufgabe Tool Calls, Exit-Code, Diff und ollama ps. Erweitere den Umfang erst, wenn diese Signale stabil sind.

Übersteigt die Aufgabe den Rechner, benötigt sie eine nicht unterstützte Anthropic-Funktion oder scheitert das lokale Modell wiederholt an echtem Code, entferne den lokalen Endpoint und wechsle bewusst zur Cloud. Ein verlässlicher Rückweg ist wertvoller, als jede Coding-Aufgabe zwangsweise lokal zu halten.