Qwen Code: der Code-Agent im Terminal mit Ollama
Qwen Code ist der von Qwen, dem Alibaba-Team, veröffentlichte Kommandozeilen-Code-Agent. Er liest Ihr Repository, ändert Dateien, führt Befehle aus und arbeitet die Schritte ab, bis die Aufgabe erledigt ist, ähnlich wie Claude Code oder OpenCode. Der für uns interessante Punkt: Er spricht das OpenAI-Protokoll und kann daher an ein Modell angeschlossen werden, das bei Ihnen über Ollama oder LM Studio läuft. Dieser Leitfaden behandelt die Installation, die lokale Anbindung, die Konfiguration des Kontexts, die den Unterschied zwischen einem nützlichen und einem sich im Kreis drehenden Agenten ausmacht, sowie die Grenzen, die Sie vor der Einführung kennen sollten.
#Was Qwen Code ist und warum Sie es lokal betreiben sollten
Qwen Code ist ein Fork von Gemini CLI, dem Open-Source-Terminalagenten von Google, den das Team Qwen an seine Qwen3-Coder-Modelle angepasst hat. Das Projekt wird unter der Apache-2.0-Lizenz auf GitHub (QwenLM/qwen-code) veröffentlicht, über npm installiert und mit dem Befehl qwen verwendet. Es übernimmt die Funktionsweise moderner Code-Agenten: Ein Modell erhält Ihre Anfrage, verfügt über Tools (Lesen und Schreiben von Dateien, Suche im Repository, Shell-Ausführung, Webanfragen, MCP-Server) und arbeitet diese Tools so lange ab, bis ein überprüfbares Ergebnis vorliegt.
Standardmäßig setzt Qwen Code auf eine Verbindung über „Qwen OAuth“: Sie melden sich mit einem Qwen-Konto an, und die Anfragen gehen an die Server von Alibaba Cloud. Für diesen Weg gibt es ein kostenloses Angebot, aber seine Kontingente können sich ändern und hängen von der Region ab. Daher nennen wir hier keine Zahl: Die Authentifizierungsseite der offiziellen Dokumentation ist die einzige aktuelle Quelle. Unverändert bleibt der andere Modus, genannt „OpenAI-kompatibel“: Qwen Code akzeptiert jeden Server, der die OpenAI-API bereitstellt, darunter Ollama und LM Studio auf Ihrem Rechner.
- Datenschutz
- Im lokalen Modus verlassen Quellcode, ausgeführte Befehle und deren Ausgaben niemals den Rechner. Das ist das entscheidende Argument für Kundencode oder Code unter einer Vertraulichkeitsvereinbarung.
- Kosten
- Kein Kontingent, keine Abrechnung pro Token. Die einzigen Kosten sind Strom und die bereits gekaufte Hardware.
- Verfügbarkeit
- Keine Dienstausfälle, keine Warteschlange zu Spitzenzeiten. Der Agent antwortet, solange die GPU läuft.
- Nachteil
- Ein Modell mit 7 bis 30 Milliarden Parametern in Q4-Quantisierung erreicht nicht das Niveau eines Cloud-Modells mit mehreren hundert Milliarden Parametern. Sie müssen Aufgaben feiner aufteilen und mehr gegenlesen.
#Voraussetzungen
Dieser Guide führt Sie zum Modell. Das Kit führt Sie zum Copiloten, der in Ihrem Editor Code schreibt.
- Lebenslanger Online-Zugang
- PDF + Dateien
- Lebenslange Updates
- Node.js 20 oder neuer
- Qwen Code ist ein npm-Paket. Überprüfen Sie dies mit node --version. Unter Linux und macOS vermeiden nvm oder fnm Berechtigungsprobleme bei der globalen Installation.
- Ollama installiert und funktionsfähig
- Der Daemon lauscht auf http://localhost:11434. Ein ollama list muss fehlerfrei antworten. Falls nicht, beginnen Sie mit dem Installationsleitfaden für Ollama.
- Ein Modell, das Tool-Aufrufe unterstützt
- Das ist nicht verhandelbar: Ein Code-Agent reiht strukturierte Tool-Aufrufe aneinander. Die Modelle der Familien Qwen3-Coder und Qwen2.5-Coder sowie Devstral unterstützen dies unter Ollama. Ein Modell ohne Tool-Unterstützung gibt anstelle von Aktionen Text aus, und der Agent bleibt stecken.
- GPU-Speicher
- Richtwerte für Q4_K_M: Ein 7B belegt etwa 5 GB VRAM, ein 14B etwa 9 GB, ein 32B etwa 19 GB, jeweils ohne Kontext. Der lange Kontext, den ein Agent benötigt, fügt mehrere Gigabyte hinzu: Planen Sie großzügig.
- Ein Git-Repository
- Nicht zwingend erforderlich, aber dringend empfohlen. Der Agent verändert Dateien; git diff und git checkout sind Ihr Sicherheitsnetz.
#1. Qwen Code installieren
Die vom Repository empfohlene Installation erfolgt global über npm. Unter macOS wird außerdem ein Homebrew-Paket veröffentlicht. Das Binärprogramm heißt qwen.
Beim ersten Start von qwen ohne Konfiguration fordert das Tool Sie auf, eine Authentifizierungsmethode auszuwählen. Wählen Sie Qwen OAuth nicht, wenn Ihr Ziel die lokale Nutzung ist: Wählen Sie die OpenAI-Option oder beenden Sie das Tool besser und bereiten Sie zunächst die im nächsten Schritt beschriebene Konfiguration vor. Sie können die Methode später in einer Sitzung jederzeit mit dem Befehl /auth ändern.
#2. Qwen Code mit Ollama verbinden
Ollama stellt unter dem Pfad /v1 von Port 11434 eine OpenAI-kompatible API bereit. Qwen Code liest für diesen Modus drei Umgebungsvariablen: die Basis-URL, einen API-Schlüssel und den Modellnamen. Ollama verlangt keinen Schlüssel, aber Qwen Code akzeptiert keinen leeren Wert, daher tragen wir eine beliebige Zeichenfolge ein.
- 01Ein mit Tools kompatibles Codemodell herunterladenBeispiel mit Qwen3-Coder 30B-A3B, einem Mixture-of-Experts-Modell (MoE) mit 30 Milliarden Parametern, von denen bei jedem Token 3 Milliarden aktiv sind, wodurch es für seine Größe schnell ist. Es belegt in Q4 etwa 19 GB: Sie benötigen 24 GB VRAM oder einen Apple-Silicon-Rechner mit mindestens 32 GB Unified Memory, um es vollständig auf der GPU zu halten. Auf einer 12-GB-Karte nehmen Sie besser qwen2.5-coder:7b oder ein 14B-Modell.
- 02Prüfen, ob die OpenAI-API von Ollama antwortetEine Anfrage an /v1/models muss Ihre Modelle auflisten. Schlägt sie fehl, wurde Ollama nicht gestartet oder lauscht an einer anderen Adresse.
- 03Die .env-Datei im Stammverzeichnis des Projekts erstellenQwen Code lädt automatisch eine .env-Datei, die im aktuellen Ordner, in einem .qwen-Unterordner des Projekts oder in ~/.qwen für eine globale Konfiguration vorhanden ist. Die Datei, die dem Arbeitsordner am nächsten liegt, hat Vorrang.
- 04qwen im Projekt startenAm unteren Rand des Fensters wird das aktive Modell angezeigt. Wenn Sie den Namen Ihres Modells Ollama sehen, ist die Verbindung hergestellt. Geben Sie eine erste einfache Anfrage ein, zum Beispiel die Struktur des Repositorys zusammenzufassen, um zu prüfen, ob die Lesewerkzeuge funktionieren.
Dieselben Parameter können für eine einzelne Sitzung als Befehlszeilenoptionen übergeben werden, ohne die .env-Datei anzufassen. Das ist praktisch, um ein zweites Modell zu testen, ohne die funktionierende Konfiguration zu beschädigen.
#3. Variante: LM Studio als Server
Wenn Sie LM Studio bevorzugen, ist das Prinzip identisch. Laden Sie ein Code-Modell in die Anwendung, öffnen Sie den Tab Developer und starten Sie den lokalen Server: Er lauscht standardmäßig auf Port 1234 und stellt dieselbe OpenAI-kompatible API bereit. Aktivieren Sie in den Serveroptionen gegebenenfalls die Unterstützung für Tool-Aufrufe und stellen Sie die Kontextlänge des Modells in der Oberfläche ein (siehe den nächsten Schritt).
Der anzugebende Modellname ist die von LM Studio in der Liste der geladenen Modelle angezeigte oder über eine Anfrage an http://localhost:1234/v1/models zurückgegebene Kennung. Sie unterscheidet sich von den Namen Ollama.
#4. Das Kontextfenster einstellen: der Schritt, den alle überspringen
Das ist die häufigste Ursache für Fehler von Qwen Code im lokalen Betrieb. Ein Code-Agent sendet bei jedem Durchlauf einen langen System-Prompt (Tool-Beschreibung, Verhaltensregeln, Inhalt der Datei QWEN.md), danach den Sitzungsverlauf und anschließend die gelesenen Dateien. Schon nach den ersten Interaktionen werden 10.000 Tokens überschritten. Ollama öffnet standardmäßig jedoch ein kurzes Fenster (in neueren Versionen 4.096 Tokens): Alles, was darüber hinausgeht, wird stillschweigend abgeschnitten, das Modell „vergisst“ die Tool-Anweisungen und beginnt, in Prosa zu antworten, statt zu handeln, oder wiederholt dieselbe Aktion in einer Schleife.
Sie müssen daher einen Kontext von mindestens 32.000 Tokens erzwingen. Unter Ollama gibt es dafür zwei Methoden: eine globale Umgebungsvariable für den Daemon oder eine Modelfile, die num_ctx für ein bestimmtes Modell festlegt.
Die zweite Methode ist sauberer: Sie wirkt sich nicht auf die anderen Modelle aus, und der Name des abgeleiteten Modells erinnert an seine Einstellung. Der Nachteil ist der Speicherbedarf: Der Key-Value-Cache wächst mit dem Kontext. Bei einem 7B-Modell in Q4 fügen 32.000 Kontext-Tokens je nach Architektur und Quantisierung des Caches grob 2 bis 4 GB hinzu. Passt das Modell nicht mehr vollständig in den GPU-Speicher, lagert Ollama einen Teil der Schichten auf die CPU aus und die Geschwindigkeit bricht ein: Überwachen Sie die Spalte PROCESSOR von ollama ps; sie sollte 100 % GPU anzeigen.
Auch auf der Seite von Qwen Code gibt es eine Sitzungsbegrenzung. Die Einstellung sessionTokenLimit in der Einstellungsdatei begrenzt die Gesamtzahl der Tokens eines Gesprächs; sobald sie erreicht ist, fordert das Tool Sie auf, den Verlauf mit /compress zu komprimieren oder mit /clear von vorn zu beginnen. Stimmen Sie diesen Wert auf das ab, was Ihr Modell tatsächlich unterstützt: Ein Limit von 32 000 für ein mit num_ctx 32768 bereitgestelltes Modell verhindert stille Abschneidungen auf der Seite von Ollama.
#5. Einstellungsdatei und QWEN.md
Qwen Code liest eine settings.json-Datei auf zwei Ebenen: ~/.qwen/settings.json für den Benutzer und .qwen/settings.json im Projekt, die Vorrang hat. Die nützlichsten Schlüssel für den lokalen Betrieb sind das Sitzungslimit, der Genehmigungsmodus für Aktionen und die MCP-Server. Die genauen Namen haben sich zwischen den Versionen geändert; das folgende Beispiel folgt der öffentlichen Dokumentation und muss mit der Settings-Seite Ihrer Version abgeglichen werden.
Die Datei QWEN.md erfüllt dieselbe Funktion wie CLAUDE.md für Claude Code oder AGENTS.md für andere Agenten: Sie ist das permanente Memo, das in jede Sitzung eingefügt wird. Beschreiben Sie darin den Stack, die Build- und Testbefehle, die Namenskonventionen und was der Agent niemals anfassen darf. Der Befehl /init erzeugt daraus anhand des Repositorys eine erste Version; /memory show zeigt an, was der Agent tatsächlich geladen hat.
Der Genehmigungsmodus steuert, was der Agent tun kann, ohne Sie zu fragen. Standardmäßig wartet jeder Dateischreibvorgang und jeder Shell-Befehl auf Ihre Bestätigung. Die Option --approval-mode auto-edit lässt Dateiänderungen zu, aber keine Befehle; --yolo entfernt jede Bestätigung. Bei einem lokalen Modell, das sich häufiger irrt als ein Cloud-Modell, behalten Sie den Standardmodus bei, solange Sie ihm noch nicht vertrauen, und verwenden Sie --yolo nur in einem sauberen, committeten Repository.
#6. Erste Arbeitssitzung
Eine Sitzung von Qwen Code wird in natürlicher Sprache mit einigen Tastenkürzeln gesteuert. Das Präfix @ fügt eine Datei oder einen Ordner in die Anfrage ein (@src/api/routes.py), das Präfix! führt einen Shell-Befehl aus, ohne das Modell zu verwenden, und Befehle, die mit / beginnen, steuern das Tool selbst.
- /help
- Liste der in Ihrer Version verfügbaren Befehle.
- /auth
- Ändert die Authentifizierungsmethode, nützlich für den Wechsel zwischen lokal und Cloud.
- /model
- Zeigt das aktuelle Modell an oder ändert es.
- /stats
- Verbrauchte Tokens und Sitzungsdauer: der erste Ansatzpunkt, wenn die Antworten schlechter werden.
- /compress
- Fassen Sie den Verlauf zusammen, um Kontext freizugeben, ohne den Zusammenhang zu verlieren.
- /clear
- Startet ein leeres Gespräch; die QWEN.md bleibt geladen.
- /init et /memory
- Generiert und prüft die Kontextdatei des Projekts.
- /mcp
- Status der konfigurierten MCP-Server und der von ihnen bereitgestellten Tools.
- /quit
- Beendet die Sitzung.
Ein Ablauf, der mit einem lokalen Modell gut funktioniert: Bitten Sie zuerst um eine Analyse („erkläre, wie die Authentifizierung in @src/auth/ verwaltet wird“), dann um eine begrenzte Änderung („füge eine Prüfung des Token-Ablaufs in verify_token und einen entsprechenden Test hinzu“) und anschließend um eine Überprüfung („führe make test aus und behebe, was fehlschlägt“). Jeder Schritt umfasst einige Tausend Tokens, und das Modell behält den Zusammenhang bei. Anfragen wie „refaktorisiere das gesamte Modul“ überschreiten das, was Modelle mit 7 bis 30B Parametern zuverlässig bewältigen.
Für die Automatisierung nimmt der nicht-interaktive Modus eine Anfrage als Argument entgegen und gibt die Kontrolle nach Abschluss zurück. Er lässt sich in ein Skript oder einen Git-Hook integrieren.
#Grenzen von Qwen Code lokal
Qwen Code wurde für die von Alibaba Cloud bereitgestellten Qwen3-Coder-Modelle entwickelt, und das merkt man sofort, wenn man es mit einem kleineren lokalen Modell betreibt. Folgendes müssen Sie akzeptieren.
- Schwergewichtiger System-Prompt
- Das Tool sendet bei jedem Durchlauf eine lange Tool-Beschreibung. Bei einem 7B-Modell nimmt diese einzelne Anweisung einen beträchtlichen Teil des Kontexts und der Aufmerksamkeit des Modells ein, das dadurch das Format für Tool-Aufrufe schlechter einhält als größere Modelle. Schleifen und Antworten in Prosa statt Aktionen treten häufiger auf als bei OpenCode oder Aider, die kompaktere Prompts verwenden.
- Vision ausschließlich in der Cloud
- Die Unterstützung für Bilder (Screenshots, Mock-ups) basiert auf online bereitgestellten Vision-Modellen. Lokal funktioniert sie nur, wenn Ihr Server ein kompatibles multimodales Modell bereitstellt, was bei den meisten Code-Modellen nicht der Fall ist.
- Keine native Verwaltung lokaler Modelle
- Im Gegensatz zu OpenCode, das die Modelle Ollama in einem Menü auflistet, verlangt Qwen Code, dass Sie den Modellnamen und die URL in einer Datei oder als Option eingeben. Ein Modellwechsel bedeutet, die .env-Datei zu ändern oder den Befehl mit --model erneut auszuführen.
- Unbeständiges Konfigurationsformat
- Das Projekt ist jung, und seine Datei settings.json hat sich im Laufe der Versionen strukturell verändert. Ein in einem Forum gefundenes Beispiel ist möglicherweise nicht mehr gültig. Maßgeblich ist die offizielle Dokumentation zum Zeitpunkt des Lesens.
- Bearbeitung durch Neuschreiben
- Wie Gemini CLI, von dem es abgeleitet ist, ändert Qwen Code Dateien durch das Ersetzen von Blöcken. Aider wendet dagegen Unified Diffs an und committet jede Änderung automatisch, wodurch der Verlauf übersichtlicher wird. Wenn Sie pro Änderung einen Commit möchten, ist Aider weiterhin besser geeignet.
Im Gegenzug bietet Qwen Code vollständige MCP-Unterstützung, ausgereifte Sitzungsverwaltungsbefehle aus Gemini CLI, einen sauberen nicht interaktiven Modus und eine Integration, die sich über Erweiterungen auf IDEs erstreckt. Das ist sinnvoll, wenn Sie bereits die Modelle Qwen verwenden und ein einziges Tool für den Wechsel zwischen der Alibaba-Cloud und Ihrer GPU möchten. Wenn das Ziel ausschließlich die lokale Nutzung ist, erfordern OpenCode oder Aider weniger Einstellungen, um dasselbe Ergebnis zu erzielen. Wir veröffentlichen keinen Zahlenvergleich: Die Qualität hängt in erster Linie vom gewählten Modell ab, nicht vom Agenten.
#Fehlerbehebung
- Der Agent antwortet als Text, statt Aktionen auszuführen
- Entweder unterstützt das Modell keine Tool-Aufrufe (prüfen Sie seine Beschreibung Ollama), oder der Kontext ist zu kurz und die Beschreibung der Tools wurde abgeschnitten. Führen Sie Schritt 4 aus und prüfen Sie mit ollama ps, ob das Modell mit dem richtigen num_ctx geladen ist.
- Fehler 404 oder „model not found“
- Der Name in OPENAI_MODEL stimmt nicht exakt mit ollama list überein. Kopieren Sie den Namen einschließlich seines Tags.
- Verbindungsfehler auf localhost:11434
- Ollama läuft nicht oder lauscht auf einer anderen Schnittstelle (OLLAMA_HOST). Testen Sie mit curl http://localhost:11434/v1/models.
- Sehr langsame Antworten nach einigen Interaktionen
- Der Kontext ist gewachsen und das Modell wird aus dem GPU-Speicher verdrängt. ollama ps zeigt einen CPU-Anteil an. Verringern Sie num_ctx, wechseln Sie zu einem kleineren Modell oder führen Sie /compress früher in der Sitzung aus.
- Qwen Code fordert erneut eine OAuth-Authentifizierung an
- Die Umgebungsvariablen werden nicht gelesen: Die .env-Datei befindet sich weder im aktuellen Ordner noch in ~/.qwen. Starten Sie /auth in der Sitzung und wählen Sie die OpenAI-Option oder übergeben Sie die Parameter in der Befehlszeile, um das Problem einzugrenzen.
- Das Modell ignoriert die QWEN.md
- Prüfen Sie mit /memory show, ob die Datei geladen ist. Wenn contextFileName in settings.json geändert wurde, muss der Name übereinstimmen.
- Fehlschlagende npm-Installation mit EACCES
- Unzureichende Berechtigungen für das globale npm-Verzeichnis. Installieren Sie Node über nvm oder fnm statt über das Systempaket und starten Sie die Installation anschließend erneut.
#Weiterführende Informationen
Qwen Code ist nur einer der Terminal-Agenten, die einen lokalen Server akzeptieren. Die folgenden Anleitungen behandeln die Alternativen und die Wahl des Modells, was dieser Artikel bewusst ausklammert.
- OpenCode + Ollama: ein Code-Agent in Ihrem Terminal
- Aider + Ollama: Im Terminal mit einem zu 100 % lokalen Agenten programmieren
- Goose (Block): Der lokale KI-Agent in Ihrem Terminal
- Bestes lokales LLM zum Programmieren: Devstral, Qwen3-Coder
Leitfaden verfasst am 11. Oktober 2026; als Quellen dienten das GitHub-Repository und die Dokumentation von Qwen Code sowie die Dokumentation von Ollama. Für diesen Artikel wurden keine Geschwindigkeits- oder Qualitätsmessungen durchgeführt; die Angaben zum Speicherbedarf sind Größenordnungen. Befehle und Schlüsselnamen ändern sich mit den Versionen: Überprüfen Sie sie auf den unten verlinkten Seiten, bevor Sie sie kopieren.
- GitHub-Repository QwenLM/qwen-code (README, Installation, Lizenz)
- Offizielle Dokumentation zu Qwen Code (Authentifizierung, settings, Befehle)
- Dokumentation Ollama (OpenAI-kompatible API, Umgebungsvariablen)
Haben Sie Feedback, einen Fehler entdeckt oder möchten Sie etwas präzisieren? Geben Sie uns Bescheid – so wird der Guide für alle besser.