Anleitung zur lokalen Einrichtung von Claude Code mit Ollama

Claude Code ist der offizielle Terminal-Programmierassistent von Anthropic und kommuniziert standardmäßig mit der Cloud-API von Anthropic. Ollama ist ein lokaler Modellausführungs-Manager, der eine mit der OpenAI-API kompatible HTTP-Schnittstelle bereitstellt. Beide Systeme sprechen standardmäßig nicht dieselbe Protokollsprache, sodass ihre Kombination eine kleine Proxy-Schicht erfordert, die die Messages-API von Anthropic in die Chat-API von Ollama übersetzt. Diese Anleitung erklärt, wie das funktioniert, welche Modelle sich lohnen und an welchen Stellen die Einrichtung an ihre Grenzen stößt.

Warum Ollama und Claude Code nicht direkt miteinander verbunden werden können

Claude Code sendet Anfragen im Messages-API-Format von Anthropic (/v1/messages) mit anthropeigenspezifischen Feldern für Tool-Nutzung, Cache-Steuerung und System-Prompts. Ollama stellt dagegen einen /api/chat -Endpunkt und einen mit der OpenAI-API kompatiblen /v1/chat/completions -Endpunkt bereit. Keiner dieser Endpunkte spricht die Anthropic-Dialektsprache. Um beide Systeme zu verbinden, benötigen Sie einen Proxy, der:

• Anfragen im Anthropic-Format über einen HTTPS-Endpunkt akzeptiert.
• Sie in OpenAI-kompatible Chat-Completions umschreibt.
• An Ollama weiterleitet und dann gestreamte Antworten sowie Tool-Aufrufe wieder in den Anthropic-Event-Stream übersetzt, den Claude Code erwartet.

Zwei Projekte bewältigen dies zuverlässig (Stand 2026): claude-code-router (ein speziell für Claude Code entwickelter Router mit Unterstützung für Ollama, OpenRouter und andere Backends) sowie LiteLLM (ein universeller Proxy mit einem Anthropic -Durchleitungsbetrieb). Beides funktioniert; claude-code-router ist einfacher, wenn Ollama Ihr einziger Backend-Dienst ist.

Voraussetzungen

• Ollama installiert und ausgeführt. Siehe So installieren Sie Ollama falls Sie Ollama noch nicht installiert haben.
• Claude Code installiert (npm install -g @anthropic-ai/claude-code).
• Mindestens ein programmierfähiges Modell lokal heruntergeladen.
• Node.js 18+ für claude-code-router oder Python 3.10+ für LiteLLM.

Überprüfen Sie, ob Ollama erreichbar ist:

curl http://localhost:11434/api/tags

Auswahl eines lokalen Modells

Claude Code setzt stark auf Tool-Nutzung, strukturierte Änderungen und Schlussfolgerungen über lange Kontexte hinweg. Kleinere Allgemein-Chat-Modelle bewältigen diese Aufgaben schlecht. Verwenden Sie daher ausschließlich auf Programmierung optimierte Modelle oder große Instruct-Modelle.

Der Quantisierungsgrad, die Kontextlänge und die Größe des KV-Caches beeinflussen sämtlich den VRAM-Bedarf. Verwenden Sie den VRAM-Rechner zur genauen Abschätzung einer bestimmten Konfiguration und sehen Sie sich beste lokale LLMs für Ollama für einen umfassenderen Vergleich an.

Ziehen Sie ein Modell, bevor Sie den Proxy konfigurieren:

ollama pull qwen3-coder:30b
ollama pull deepseek-coder-v2:16b

Option 1: claude-code-router

claude-code-router ist der kürzeste Weg. Installieren Sie es global:

npm install -g @musistudio/claude-code-router

Erstellen Sie ~/.claude-code-router/config.json:

{
  "Providers": [
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen3-coder:30b", "deepseek-coder-v2:16b"]
    }
  ],
  "Router": {
    "default": "ollama,qwen3-coder:30b",
    "background": "ollama,deepseek-coder-v2:16b"
  }
}

Starten Sie Claude Code über den Router:

ccr code

Der Router startet einen lokalen, mit Anthropic kompatiblen Endpunkt, setzt automatisch die erforderlichen Umgebungsvariablen für Claude Code und leitet den Datenverkehr an Ollama weiter. Die genauen Namen der Konfigurationsfelder haben sich zwischen Minor-Versionen geändert – prüfen Sie bei Ablehnung eines Schlüssels die README-Datei des Projekts.

Option 2: LiteLLM-Proxy

Falls Sie LiteLLM bereits für andere Dienste betreiben, können Sie es wiederverwenden. Erstellen Sie config.yaml:

model_list:
  - model_name: claude-sonnet-4
    litellm_params:
      model: ollama_chat/qwen3-coder:30b
      api_base: http://localhost:11434
  - model_name: claude-haiku-4
    litellm_params:
      model: ollama_chat/deepseek-coder-v2:16b
      api_base: http://localhost:11434

Starten Sie es mit:

litellm --config config.yaml --port 4000

Verweisen Sie dann Claude Code auf den Proxy (siehe nächsten Abschnitt). LiteLLM übernimmt die Übersetzung von Anthropic-zu-Ollama-Anfragen auf der /anthropic -Route.

Konfiguration von Claude Code für die Nutzung des Proxys

Claude Code liest zwei Umgebungsvariablen, um seinen API-Datenverkehr umzuleiten. Legen Sie diese in Ihrer Shell fest, bevor Sie claude.

macOS und Linux

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-anything"
claude

Fügen Sie diese Einträge zur ~/.zshrc oder ~/.bashrc hinzu, um sie dauerhaft zu speichern. Der API-Schlüssel wird vom lokalen Proxy nicht genutzt, doch Claude Code startet ohne gesetzten Wert nicht.

Windows (PowerShell)

$env:ANTHROPIC_BASE_URL="http://localhost:4000"
$env:ANTHROPIC_API_KEY="sk-anything"
claude

Um die Variablen dauerhaft zu speichern, verwenden Sie [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "http://localhost:4000", "User"). Falls Claude Code über WSL installiert ist, konfigurieren Sie die Variablen stattdessen innerhalb der WSL-Shell – Ollama unter Windows ist von WSL aus unter http://host.docker.internal:11434 oder der IP-Adresse des Windows-Hosts erreichbar.

Windows (nativer Betrieb, ohne WSL)

Claude Code richtet sich offiziell an macOS, Linux und WSL. Die native Windows-Unterstützung war historisch gesehen problematisch; führen Sie es daher unter WSL2 aus, es sei denn, Sie haben bestätigt, dass die aktuelle Version auf Ihrem System fehlerfrei läuft.

Anpassung von Kontextgröße und Timeouts

Claude Code geht von einem Kontext von 200K-Token und einer schnellen Zeit bis zum ersten Token aus. Lokale Modelle erreichen beides nicht. Zwei Einstellpunkte sind entscheidend:

• Ollama-Kontextlänge. Legen Sie sie explizit pro Modell über eine Modelfile fest (PARAMETER num_ctx 32768) oder über die OLLAMA_CONTEXT_LENGTH Umgebungsvariable auf dem Ollama-Server. Die Standardkontextlänge ist klein und führt bei langen Gesprächen stumm zu Trunkierung.
• KV-Cache-VRAM. Ein Kontext von 32K verbraucht bei einem 30B-Modell allein mehrere GB VRAM für den KV-Cache. Prüfen Sie die gesamte Speicherauslastung mit ollama ps.

Für eine detaillierte Aufschlüsselung des Speicherbedarfs bei verschiedenen Kontextgrößen siehe VRAM-Anforderungen nach Modell.

Bekannte Einschränkungen

• Die Nutzung von Tools ist fehleranfällig. Claude Codes Dateibearbeitungs-, Bash- und Suchtools setzen strikt formatierte JSON-Tool-Aufrufe voraus. Lokale Modelle versagen hier häufiger und erzeugen entweder fehlerhafte Aufrufe oder halluzinieren Dateiinhalte. qwen3-coder und deepseek-coder-v2 gehören zu den zuverlässigsten lokalen Modellen, doch keines erreicht das Niveau von Claude Sonnet.
• Prompt-Caching hat keine Wirkung. Anthropics cache_control -Felder werden vom Proxy ignoriert. Lange System-Prompts werden bei jedem Turn erneut gesendet.
• Geschwindigkeit. Selbst auf einer 24-GB-GPU erzeugt ein 30B-Modell bei einer Kontextlänge von 32K nur 15–40 Tokens/Sekunde. Da Claudes agenter Loop pro Aufgabe zahlreiche Aufrufe tätigt, kann die Gesamtlaufzeit 5–10-mal länger sein als bei der Cloud-API.
• Sub-Agents und MCP. Fortgeschrittene Funktionen von Claude Code (Hintergrund-Agents, MCP-Server) funktionieren im Allgemeinen weiterhin, da sie denselben Proxy durchlaufen; Funktionen, die auf Anthropic-spezifischem Serververhalten beruhen, können jedoch stillschweigend versagen.

Wann diese Einrichtung statt der Cloud-API sinnvoll ist

Ein lokaler Betrieb von Claude Code ist sinnvoll, wenn: Code Ihr Netzwerk nicht verlassen darf, Sie ein begrenztes API-Budget haben und umfangreiche Refactorings durchführen oder Sie mit Self-Hosting experimentieren. Für den täglichen Einsatz beim agenterischen Programmieren, bei dem die Denkleistung auf Sonnet-Niveau im Vordergrund steht, ist er hingegen weniger geeignet.

Um eine numerische Entscheidung zu treffen, berechnen Sie die Kosten beider Varianten. Der API-Kostenrechner schätzt die monatlichen Anthropic-Ausgaben ab, und der Selbsthosting- versus-API-Kosten-Grenzwert-Rechner vergleicht diese mit den amortisierten GPU-Kosten. Für die meisten Einzelentwickler ist die API die bessere Wahl; für Teams mit starkem API-Aufkommen kann sich ein gemeinsamer lokaler Rechner innerhalb eines Jahres amortisieren. Wenn Sie diesen Rechner dimensionieren, hilft Ihnen der beste GPUs für lokale LLMs -Leitfaden mit der aktuellen Hardware-Stufe weiter.

Alternativen zu Ollama für diesen Workflow

Wenn die Leistung von Ollama die Nutzung einschränkt, funktionieren andere Laufzeitumgebungen mit OpenAI-kompatiblen APIs hinter derselben Proxy-Schicht identisch: LM Studio, vLLM und der Server von llama.cpp passen alle dazu. Siehe die LM Studio-Anleitung für eine GUI-zentrierte Option oder die Kompletter Ollama-Leitfaden für eine ausführlichere Betrachtung von Ollama selbst.

Häufig gestellte Fragen

Kann Claude Code Ollama ohne Proxy nutzen?

Nein. Claude Code kommuniziert über die Messages-API von Anthropic, die Ollama nicht implementiert. Sie benötigen eine Übersetzungsschicht wie claude-code-router oder LiteLLM. Die direkte Einstellung von ANTHROPIC_BASE_URL auf http://localhost:11434 schlägt bei der ersten Anfrage fehl.

Welches lokale Modell kommt dem Codierungsvermögen von Claude Sonnet am nächsten?

Bei den Modellgrößen, die die meisten Nutzer tatsächlich lokal betreiben können, sind qwen3-coder (30B MoE) und deepseek-coder-v2 (16B lite) derzeit die besten Wahl. Keines davon erreicht Sonnet bei Multi-Datei-Agentenaufgaben, aber beide eignen sich für Einzel-Datei-Bearbeitungen, Code-Vervollständigungen und Code-Reviews. Vergleichen Sie die Intelligenz-Werte auf dem LLM-Leaderboard.

Funktioniert Prompt-Caching mit Ollama hinter Claude Code?

Nein. Das Prompt-Caching von Anthropic ist eine serverseitige Funktion ihrer API. Proxies entfernen oder ignorieren die cache_control -Felder, sodass bei jeder Anfrage der gesamte System-Prompt und der gesamte Konversationsverlauf erneut verarbeitet werden müssen. Dies ist einer der Gründe, warum lokale Setups pro Turn langsamer wirken als die Cloud-API – selbst bei vergleichbarer Rohdurchsatzrate an Tokens.

Wie viel VRAM benötige ich für ein angemessenes Erlebnis?

Eine einzelne 24-GB-GPU (RTX 3090/4090/5090-Klasse) ermöglicht den Betrieb eines 30B-Coder-Modells in Q4-Qualifizierung mit etwa 32K Kontext. Für Modelle der 70B-Klasse oder längere Kontexte planen Sie mindestens 48 GB (RTX 6000 Ada, zwei RTX 3090) oder mehr ein. Nutzen Sie den VRAM-Rechner für exakte Zahlen zu jedem Modell und jeder Quantisierung.

Kann ich lokale und Cloud-Modelle innerhalb derselben Claude-Code-Sitzung mischen?

Ja, mithilfe eines Routers. claude-code-router ermöglicht es Ihnen, verschiedenen Rollen unterschiedliche Modelle zuzuweisen – beispielsweise Cloud-Sonnet für den Haupt-Agenten und ein lokales Modell für Hintergrundaufgaben oder Vervollständigungen. Dadurch lassen sich die API-Kosten erheblich senken, während die Qualität bei kritischen Aufgaben hoch bleibt.

Gibt es eine offiziell von Anthropic unterstützte Möglichkeit, Claude Code lokal auszuführen?

Nein. Anthropic stellt Claude Code als Client für ihre API bereit und verteilt keine Claude-Weights. Alle lokalen Setups basieren auf Community-Proxies, die auf Drittanbietermodelle verweisen. Falls Anthropic die Messages-API ändert, müssen möglicherweise auch die Proxies aktualisiert werden, bevor Claude Code wieder mit ihnen funktioniert.