Lokale Codierungsagenten auf einem Mac mit oMLX ausführen: Erklärung des auf der Festplatte gespeicherten KV-Caches

Nach zwölf Minuten einer Programmier-Sitzung hört das lokale Modell auf, sich wie ein Agent zu verhalten, und beginnt stattdessen wie ein Faxgerät zu funktionieren. Früher kamen die Antworten auf Tool-Aufrufe bereits nach zwei Sekunden. Jetzt dauert jeder Schritt dreißig, manchmal sogar neunzig Sekunden. Die Aufgabe selbst hat sich nicht geändert – der Kontext ist einfach länger geworden, und der lokale Server rechnet bei jedem Anfrage jede gesamte Konversation von vorne aus.

Dieses Symptom, nämlich langsame Starts statt langsamer Token-Verarbeitung, sollte durch ein kleines Projekt namens oMLX auf Apple Silicon beseitigt werden. Es handelt sich dabei weder um ein Modell noch um einen Agent – es ist vielmehr ein Inferenzserver mit einem klaren Ziel: Alles, was der Agent bereits gelesen hat, bleibt im Cache, auch wenn der Sitzungsumfang zunimmt, sodass der zwölfte Schritt sich wie der erste anfühlt. Der echte Test besteht nicht in einer auffälligen Demonstration, sondern darin, wie das System bei Schritt vierzig einer echten, funktionierenden Sitzung auf dem eigenen Hardware-System abschneidet.

Warum Macs mit Programmier-Agenten zu kämpfen haben

Ursprünglich ist Apple Silicon eine starke Plattform für lokale Inferenz. Die vereinigte Speicherlösung stellt dem CPU und der GPU einen gemeinsamen Speicherpool zur Verfügung, sodass ein quantisiertes Modell im RAM bleibt, ohne den Datenbus nutzen zu müssen. Apples MLX-Framework wurde speziell für diese Art von Arbeitslast entwickelt.

Probleme entstehen, wenn das Chatten in Agentenarbeit übergeht. Ein Programmieragent liest fast bei jedem Schritt den größten Teil seines früheren Kontexts erneut, ruft ein Tool auf, erhält das Ergebnis angehängt an die Anfrage und wiederholt diesen Vorgang Dutzende Male. Der Präfix, also der gemeinsame Anfang der Anfrage, stimmt fast mit dem vorherigen Schritt überein, abgesehen von einem neuen Tool-Ergebnis am Ende.

Die meisten lokalen Server betrachten einen solchen Teilübereinstimmungsfall als völlige Unübereinstimmung, löschen den Schlüssel-Wert-Cache und berechnen alles von vorne. Bei kurzen Anfragen bemerkt das niemand. Bei einer Sitzung mit 20.000 Tokenen führt das jedoch dazu, dass eine Antwort, die zwei Sekunden dauert, von einer Antwort, die neunzig Sekunden dauert, unterschieden wird. Der Schöpfer des Projekts nannte genau dies als Motivation im Apple MLX-Forum: Codierende Agenten senden Anfragen, deren Präfixe sich ändern, und jeder vorhandene MLX-Server macht den Cache ungültig und berechnet alles neu, wenn das geschieht.

Was oMLX ist

oMLX ist ein Open-Source-Inferenzserver, der auf Apple’s MLX und mlx-lm basiert. Er ist als natives macOS-Menüleisten-Programm sowie als Python-Befehlszeilenwerkzeug verfügbar. Der Entwickler Jun Kim hat ihn erstellt, und er befindet sich auf GitHub unter dem Namen jundot/omlx unter der Apache 2.0-Lizenz. Zum Zeitpunkt der Erstellung hatte er etwa 18.600 Sterne, 1.600 Forks sowie weit über zweitausend Commit-Verzeichnisse.

Nichts davon beweist Zuverlässigkeit. Sterne messen die Aufmerksamkeit und nicht die Reife, und ein Projekt, das monatlich mehrere Release-Kandidaten veröffentlicht, findet sich noch in der Entwicklungsphase. Popularität ist ein Grund, es zu testen, aber kein Ersatz für Tests.

Ein einziger Prozess bedient zwei API-Stile: OpenAI-kompatible Chat-Completions sowie eine native Anthropic-stilige /v1/messages-Route samt Completions-, Embedding- und Reranking-Routen. Er kann Sprachmodelle, Vision-Sprachmodelle, OCR-Modelle sowie Reranker zusammen geladen halten, wobei LRU-Entfernung und Modell-spezifisches Fixieren genutzt werden. Für Agenten ist entscheidend, was unter dieser Oberfläche geschieht.

Präfixe werden auf die Festplatte geschrieben, nicht in den Puffer

Bei herkömmlicher MLX-Infersion wird der Cache einer Konversation ausschließlich im GPU-Speicher gehalten, solange der Präfix weiterhin übereinstimmt. Der zentrale Ansatz bei oMLX ist ein zweistufiger Cache, der sowohl Präfix-Veränderungen als auch Neustarts überdauert. Häufig genutzte Blöcke bleiben in einem schnellen Speicherebenen im Speicher. Wenn diese Ebene voll ist, werden die Blöcke im Safetensors-Format auf eine langsamere Ebene auf der SSD geschrieben, wobei sie blockweise mit Präfix-Teilung und Copy-on-Write-Verfahren verwaltet werden. Wenn ein späterer Prompt auf einen Präfix trifft, der bereits auf die Festplatte geschrieben wurde, werden diese Blöcke wieder gelesen und nicht erneut berechnet.

Ein Bibliothekar, der ein Buch, das man kürzlich ausgeliehen hat, nie wieder ins Regal stellt, veranschaulicht dies gut. Fragt man später erneut nach – selbst nach der Wiedereröffnung der Bibliothek – liegt das Buch bereits auf dem Tresen.

Eine SSD ist kein RAM, daher dauert das Wiederherstellen eines großen Caches immer noch Zeit – allerdings ist das viel günstiger als das Neuberechnen jedes Tokens. Der größte Nutzen zeigt sich beim zuvor beschriebenen Agentenmuster: langen, meist wiederholten Präfixen mit einer kleinen Veränderung am Ende. Der Server führt außerdem durch den BatchGenerator von mlx-lm kontinuierliches Batching durch, wodurch mehrere Anfragen gleichzeitig bearbeitet statt in einer Warteschlange abgelegt werden, wobei das Niveau über die Kommandozeile oder das Admin-Panel konfiguriert werden kann.

Zwei Werte sind am wichtigsten. Die Zeit bis zum ersten Token gibt an, wie lange es dauert, bis etwas zurückgestreamt wird. Die Generierungsgeschwindigkeit zeigt an, wie schnell die Tokens nach dem Start ankommen. Die Wiederverwendung des Caches erfolgt nach dem ersten Token, wobei der zweite unberührt bleibt. Ein Modell, das langsam generiert, bleibt weiterhin langsam, beginnt aber früher mit der Antwortgabe.

Installation auf Apple Silicon

Die Anforderungen sind macOS 15 (Sequoia) oder neuer, Python zwischen 3.11 und 3.13 sowie ein Chip aus den Familien M1, M2, M3 oder M4. Es gibt drei Möglichkeiten, wobei die erste für die meisten Menschen geeignet ist.

Die empfohlene Methode ist die macOS-App. Laden Sie die signierte und notarierte .dmg-Datei von GitHub Releases herunter, ziehen Sie sie in die Applications-Ordner und starten Sie sie. Ein Willkommensbildschirm führt Sie bei der Auswahl des Modellverzeichnisses, beim Starten des Servers und beim ersten Download, und die App installiert außerdem eine kleine Kommandozeilen-Shell.

Mit Homebrew:

brew tap jundot/omlx https://github.com/jundot/omlx
brew install omlx
omlx start

Aus der Quelle:

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e .            # core
pip install -e ".[mcp]"     # optional MCP support

Jeder, der vorhat, GLM-5.2, MiniMax M3 oder Qwen3.5 zu verwenden, sollte wissen, dass ein einfacher pip install ihre eigenen benutzerdefinierten Kerne überspringt, wodurch die betroffenen Modelle stillschweigend einen deutlich langsameren Weg wählen. Das Projekt gibt an, dass sein gefusionsbasierter Vorausfüllkern bei einem der Modelle auf einem M3 Ultra etwa 30 Mal schneller ist. Um die Kerne zu kompilieren, sind die vollständigen Xcode-Tools erforderlich – nicht nur die Command Line Tools –, was der einfachste Grund für die Verwendung der DMG-Datei ist.

Bevor Sie etwas anschließen, überprüfen Sie, ob der Server aktiv ist:

curl -s http://localhost:8000/v1/models

Eine leere Liste ist in Ordnung, wenn noch kein Modellverzeichnis festgelegt wurde.

Laden des ersten Modells

oMLX erkennt automatisch Sprachmodelle, Vision-Sprachmodelle, Embedding-Modelle sowie Reranker in dem Verzeichnis, auf das es verweist. Zudem liest es direkt einen vorhandenen Hugging Face-Cache sowie eine LM Studio-Datei, sodass nichts zweimal heruntergeladen werden muss.

omlx serve --model-dir ~/models

Das Modell sollte an die Speicherkapazität des Computers angepasst werden, nicht an die Größe der größten verfügbaren Datei. Lassen Sie macOS vier bis fünf Gigabyte Freiraum und reservieren Sie den Rest für die Gewichte sowie das Wachstum des Caches. Ein 9B-Modell im 4-Bit-Format eignet sich für Geräte mit 16 bis 32 GB Speicher. Modelle der Klasse 30 bis 40B benötigen 64 GB oder mehr. Die größten Modelle aus den eigenen Benchmarks des Projekts erfordern einen Speicher im Mac Studio von über 400 GB.

Modelle können über den in der Admin-Oberfläche integrierten Hugging Face-Browser unter http://localhost:8000/admin abgerufen werden, oder mithilfe beliebiger vorhandener hf-Download-Prozesse, die auf den Modellverzeichnis ausgerichtet sind. Eine einfache Anfrage sieht aus wie eine gewöhnliche OpenAI-Chat-Beantwortung:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "your-model-name", "messages": [{"role": "user", "content": "Say hi in five words."}]}'

Falls eine Antwort zurückkommt, funktioniert der Endpunkt.

Verbindung von Claude Code, Codex, Cursor und OpenCode

Es gibt zwei Möglichkeiten, wie oMLX mit Agenten verbunden wird, und welche davon gilt, hängt davon ab, wie der Agent seine Konfiguration speichert – nicht davon, wie gut er unterstützt wird.

Tools mit einer Konfigurationsdatei

OpenClaw, OpenCode, Codex und Pi lesen eine Konfigurationsdatei, auf die oMLX direkt zugreifen kann – JSON für die ersten beiden und TOML für Codex. Die Integrationsschnittstellen schreiben in diese Datei, und die Registerkarte „Integrationen“ im Admin-Dashboard übermittelt einen Befehl:

omlx-cli launch codex --model your-model-name --api-key your-key
omlx-cli launch opencode --model your-model-name --api-key your-key
omlx-cli launch pi --model your-model-name --api-key your-key

Durch Ausführen wird die Konfiguration des Tools aktualisiert und der Agent in einem einzigen Schritt gestartet. Jede vorhandene Konfiguration wird zunächst als mit einem Zeitstempel versehener .bak-Datei gesichert, sodass Änderungen rückgängig gemacht werden können, falls etwas nicht stimmt.

Hermes Agent und der Copilot-Eintrag

Sie beide erscheinen in der Ein-Klick-Liste im README, und die eigene Dokumentation von Hermes Agent bestätigt dies separat: Der Einrichtungswizard bietet eine Option für einen benutzerdefinierten, OpenAI-kompatiblen Endpunkt, über den auf jeden lokalen Server verweisen kann, einschließlich oMLX. Um das Dashboard zu überspringen, weisen Sie es manuell auf http://localhost:8000/v1 hin.

Der Copilot-Eintrag verdient einen zweiten Blick, bevor man sich darauf verlässt. GitHubs eigentlicher Copilot Chat authentifiziert sich über OAuth gegenüber api.githubcopilot.com und ist nicht dafür konzipiert, eine beliebige lokale Basis-URL zu verwenden. Die One-Click-Copilot-Integration zielt daher entweder auf ein anderes Tool mit demselben Namen ab oder verwendet einen Mechanismus, der in der öffentlichen Dokumentation nicht bestätigt wird. Überprüfen Sie vorab den Tab „Integrationen“, bevor Sie annehmen, dass er tatsächlich das leistet, was die Bezeichnung nahelegt.

Claude Code

Claude Code liest seine Server-Adresse beim Start aus der Umgebungsvariable ANTHROPIC_BASE_URL und nicht aus einer von oMLX bearbeitbaren Datei, wodurch die Eingabe weiterhin manuell erfolgt. Da oMLX den nativen /v1/messages-Pfad bereitstellt, ist kein Übersetzungspuffer erforderlich:

export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_AUTH_TOKEN="local"
export ANTHROPIC_DEFAULT_SONNET_MODEL="your-model-name"
export ANTHROPIC_DEFAULT_OPUS_MODEL="your-model-name"
claude

oMLX bietet außerdem Funktionen, die speziell für Claude Code entwickelt wurden. Die Berichte zur Kontextskalierung zeigen die Tokenanzahl an, sodass die automatische Komprimierung bei einem kleineren lokalen Kontextfenster korrekt ausgelöst wird, und SSE Keep-Alive verhindert Lesetimeouts während eines langen Vorausfüllvorgangs. Dies sind echte, agent-spezifische Eigenschaften und keine allgemeine Kompatibilitätsabfrage.

Cursor

Die Einstellung für das lokale Modell von Cursor befindet sich in seiner grafischen Benutzeroberfläche, sodass es kein Datei gibt, in die oMLX schreiben kann. Gehen Sie in Einstellungen unter „Modelle“ zur Abschnitt „OpenAI API“ und aktivieren Sie den Schalter „Base URL überschreiben“. Cursor hat diesen Schalter bereits zuvor umbenannt, wodurch sich die Beschriftung je nach Version unterscheiden kann. Geben Sie http://localhost:8000/v1 ein und tragen Sie einen nicht leeren String in das Feld „API-Schlüssel“ ein, da ein Server auf localhost diesen nicht überprüft. Fügen Sie das geladene Modell unter „Benutzerdefinierte Modelle“ mit seinem exakten Namen aus oMLX hinzu und deaktivieren Sie Curser’s Standardmodelle, damit diese nicht ebenfalls gegen die Server von OpenAI validiert werden.

Überprüfen, ob es tatsächlich funktioniert

Während einer echten Sitzung sollten die Panels für den heißen und kalten Cache im Admin-Dashboard kontinuierlich Blöcke sammeln und nicht bei jedem Schritt zurückgesetzt werden. Ein Reset bei jedem Schritt bedeutet in der Regel, dass der Inhalt von Systemanfragen oder Tool-Schemata zwischen den Aufrufen umgeordnet wird, was das Präfix stört.

Warm gegen Kalt messen

Anstatt eine Angabe des Anbieters einfach als Faktum hinzunehmen, kann man einen Test lokal durchführen. Korrigieren Sie das Modell, die Quantisierung, die Kontextlänge sowie die Anfragen in allen Tools und dokumentieren Sie anschließend die Zeit zum Kalten Start, die Zeit bis zum ersten Token im Kalten Modus, die Zeit bis zum ersten Token im Warmen Modus bei wiederholtem Präfix, die konstante Generierungsgeschwindigkeit, den maximalen Speicherverbrauch, das Verhalten nach 15 bis 20 simulierten Schritten des Agenten, die Einrichtungszeit sowie ob die Tool-Aufrufe während der gesamten Sitzung weiterhin korrekt interpretiert werden.

Die vom Projekt selbst veröffentlichten Zahlen, ermittelt mit einem M3 Ultra mit 512 GB und eindeutig von einem Hersteller, zeigen eine Generierungsgeschwindigkeit von etwa 45 bis 59 Tokens pro Sekunde für einen 8-Bit Qwen3-Coder-Next in Kontexten von 1k bis 32k. Durch kontinuierliches Batching wird bei acht gleichzeitigen Anfragen im Vergleich zu einer einzigen Anfrage eine Geschwindigkeitssteigerung von etwa 4,14 Mal erreicht. Das ist eine Obergrenze für High-End-Hardware und nicht das, was ein 16 GB MacBook Air leisten kann.

In einem unabhängigen Bericht wird angegeben, dass ein Kontext mit 8.700 Tokens mit herkömmlichem MLX etwa zwanzig Sekunden dauerte, während die Antwort aus dem Warm-Cache so schnell kam, dass der Autor den Benchmark ein zweites Mal durchführte, um sicherzugehen. Es handelt sich dabei um einen Bericht von Drittanbietern und nicht um einen kontrollierten Test, weshalb es sinnvoll ist, die Ergebnisse vor dem Vertrauen in sie nachzuvollziehen.

Die Zeit vom Kaltstart bis zum ersten Token unterscheidet sich nicht signifikant von der des Roh-MLX-Modells, da es noch nichts gibt, was wiederverwendet werden könnte. Der gesamte Vorteil liegt in warmen, wiederholten Anfragen mit Präfixen, die den größten Teil einer Sitzung eines Codierungs-Agenten ausmachen.

Serverbetrieb

Starten, stoppen und neu starten – wobei die Benutzeroberfläche an die Terminalanzeige angebunden ist:

omlx start          # background service, auto-restarts on crash
omlx stop
omlx restart
omlx serve --model-dir ~/models   # foreground, attached to this terminal

Bestätigen Sie, dass es läuft und ein Modell bereitstellt:

curl -s http://localhost:8000/v1/models

Verhindern Sie, dass der Speicherverbrauch mit dem Rest des Systems in Konflikt gerät:

omlx serve --model-dir ~/models --memory-guard safe
omlx serve --model-dir ~/models --memory-guard-gb 48

Stellen Sie den zweistufigen Cache direkt ein:

omlx serve --model-dir ~/models --paged-ssd-cache-dir ~/.omlx/cache
omlx serve --model-dir ~/models --hot-cache-max-size 20%

Erhöhen Sie die Konkurrenz, wenn mehrere Agenten gleichzeitig auf den Server zugreifen:

omlx serve --model-dir ~/models --max-concurrent-requests 16

Homebrew-Installationen durchlaufen denselben Lebenszyklus über brew services:

brew services start omlx
brew services stop omlx
brew services info omlx