---
# System prepended metadata

title: 當你的 Mac 終於能跑 AI Coding Agent 了：oMLX 如何用一顆 SSD 解決所有人忽略的問題

---

# 當你的 Mac 終於能跑 AI Coding Agent 了：oMLX 如何用一顆 SSD 解決所有人忽略的問題

![omlx-cover-apple-silicon-kv-cache](https://hackmd.io/_uploads/ryRR8zXqbe.jpg)

<!--
SEO Meta Description: oMLX 是專為 Apple Silicon 打造的本地 LLM 推論伺服器，透過分層式 SSD KV Cache 將 coding agent 的 TTFT 從 90 秒降到 3 秒。完整技術架構解析與實戰設定指南。
Keywords: oMLX, Apple Silicon LLM, 本地推論, MLX inference, SSD KV cache, Claude Code 本地模型
-->

凌晨兩點，我盯著終端機裡 Claude Code 的游標閃了整晚。

不是網路斷了，不是 API 炸了——是我前幾天搭的本地推論伺服器，在處理第十二輪 tool calling 之後，終於撐不住了。每一輪對話，context 越疊越長，每次都要從頭算一遍 prefill。50K token 的 context，等個一分半鐘才吐出第一個字。

說真的，這種體驗還不如直接用 API。

然後我在 Hacker News 上看到一個帖子：「SSD-backed KV cache cuts coding agent TTFT from 90s to 1s on Mac」。

一秒？我差點從椅子上摔下去。

---

## 問題到底出在哪

![omlx-before-after-ttft](https://hackmd.io/_uploads/H1Bkwf79bx.jpg)

先說清楚，為什麼本地跑 LLM 搭配 coding agent 這麼痛苦。

用過 Claude Code、OpenClaw、Codex 這類工具的人應該都有感覺——它們和一般聊天不一樣。一般聊天是你一句我一句，context 長度很穩定。但 coding agent 不是。它會讀檔案、呼叫工具、拿到結果、再決定下一步，一來一回之間 context 像吹氣球一樣膨脹。

關鍵在於：每一輪的 prompt prefix 都在變。

你讀了一個檔案，context 裡多了 2000 行程式碼。你呼叫了 grep，結果塞進去又多了 500 行。但 system prompt、之前的對話歷史——這些佔了 80% 的 context，根本沒變。

傳統推論伺服器怎麼做？**全部重算。**

每次 prefix 變了，KV cache 直接作廢，從第一個 token 重新做 prefill。在 50K-100K token 的 context 下，這意味著 30 到 90 秒的等待。每一輪都是。

oMLX 的作者 Jun Kim（首爾的一位資料工程師）顯然也被這件事搞瘋了。他在 GitHub 上寫道：

> "I build the tools I wish existed for my Mac — then open-source them."

於是他做了一個非常簡單但巧妙的設計：**把 KV cache 存到 SSD 上。**

---

## 分層式 KV Cache——這才是真正的創新

![omlx-tiered-cache-architecture](https://hackmd.io/_uploads/H1i1wzX5Zg.jpg)

說到 oMLX 的核心技術，不需要什麼高深的論文才能理解。它的設計邏輯就像你電腦裡的記憶體階層——CPU cache、RAM、SSD、硬碟，各有各的速度和容量。

oMLX 把同樣的思路搬到了 LLM 推論上。

```mermaid
graph TD
    A[新請求進入] --> B{前綴是否已快取?}
    B -->|是| C[從 Hot/Cold Tier 還原 KV blocks]
    B -->|否| D[完整 Prefill 計算]
    C --> E[只計算新增的 tokens]
    D --> F[將 KV blocks 存入 Hot Tier]
    E --> G[生成回應]
    F --> G
    G --> H{Hot Tier 超過容量?}
    H -->|是| I[LRU 淘汰至 Cold Tier SSD]
    H -->|否| J[保持在記憶體]
```

**Hot Tier**（熱層）住在 GPU 統一記憶體裡，放最近、最常用的 KV blocks。你可以用 `--hot-cache-max-size 20%` 控制它佔多少記憶體。

**Cold Tier**（冷層）住在 SSD 上，用 safetensors 格式存。那些暫時不用但以後可能用到的 KV blocks，不是被丟掉，而是被「冷藏」起來。

**Prefix Matching Engine** 負責比對：下一個請求的前綴跟之前的有多少重疊？重疊的部分直接從快取還原，只有新增的 tokens 需要計算。

效果有多誇張？根據 [oMLX 官網](https://omlx.ai/) 和 [Hacker News 討論](https://news.ycombinator.com/item?id=47247294)的數據：

| 場景 | 無 SSD Cache | 有 SSD Cache |
|------|-------------|-------------|
| **TTFT（第二輪起）** | 30-90 秒 | < 5 秒 |
| **重啟後快取** | 全部遺失 | 從 SSD 還原 |
| **10+ 輪 agent 對話** | 越來越慢 | 穩定快速 |

而且——伺服器重啟後快取還在。因為它存在磁碟上啊。這聽起來很理所當然，但之前沒人這麼做。

---

## 不只是 KV Cache：一台完整的推論伺服器

![omlx-macbook-dashboard](https://hackmd.io/_uploads/HJMxDz7qWg.jpg)

如果 oMLX 只是一個 KV cache 的 hack，它不會在一個月內拿到 [4,500 顆星](https://github.com/jundot/omlx)。它是一台功能完整的推論伺服器，而且體驗做得出乎意料地好。

### EnginePool：同時跑五種模型

不只是 LLM。oMLX 的 EnginePool 能同時管理五種類型的模型：

- **LLM**（Qwen、Llama、DeepSeek、Mistral）
- **VLM** 視覺語言模型（Qwen3.5-VL、GLM-4V）
- **Embedding**（BGE-M3、ModernBERT）
- **Reranker**（Qwen3-Reranker、XLM-RoBERTa）
- **OCR**（DeepSeek-OCR、GLM-OCR）

用 LRU 策略自動管理記憶體，用完自動卸載，常用的可以 pin 住。8GB 的 MacBook Air？v0.2.10 之後也能用了——之前的版本會預留 8GB 給系統，等於 8GB 機器 0 可用，後來改成百分比制才解決。

### API 相容：OpenAI + Anthropic 都支援

這很關鍵。oMLX 同時支援 OpenAI 和 Anthropic 兩種 API 格式，意味著你不管用 Claude Code、OpenClaw、Codex 還是 OpenCode，都能直接接上去。

```bash
# Claude Code 接本地 oMLX
export ANTHROPIC_BASE_URL=http://localhost:5050/v1

# 或者任何 OpenAI 相容的工具
export OPENAI_BASE_URL=http://localhost:5050/v1
```

在 Admin Dashboard 裡甚至可以一鍵設定這些整合——不用手動改 config 檔。

### macOS Menu Bar 原生應用

下載 DMG，拖進 Applications，系統列多一個圖示，搞定。不是 Electron，是原生的。自動更新會根據你的 macOS 版本（Sequoia 或 Tahoe）選對應的 DMG。M5 用戶還有 Neural Accelerator 專屬支援。

---

## 實測效能：數字說話

Reddit 上一位 M3 Ultra 512GB 的用戶[分享了他的 benchmark](https://www.reddit.com/r/LocalLLaMA/comments/1rdkze3/)，這些數字相當有參考價值：

| 模型 | Prompt TPS | Generation TPS | Batching 加速比 |
|------|-----------|----------------|----------------|
| Qwen3-Coder-Next 8bit | 1,462-2,009 | 45-59 | **4.14x** @ 8 concurrent |
| Qwen3.5-122B-A10B 4bit | 768-941 | 42-57 | — |
| MiniMax-M2.5 8bit | 426-704 | 15-34 | **3.71x** |
| GLM-5 4bit | 78-187 | 11-17 | **3.61x** |

*測試環境：M3 Ultra 512GB，oMLX v0.2.x*

另一位用戶在 [Reddit](https://www.reddit.com/r/LocalLLaMA/comments/1r3qwyi/) 上的評價更直白：

> "Claude Code is actually **usable on M4 Max 128GB with 6-bit Qwen3-Coder-Next**. This is the wow factor frankly; I had given up on trying to use agentic CLI locally because it's so damn slow."

根據學術研究（[arxiv: 2511.05502](https://arxiv.org/abs/2511.05502)），MLX 在 Apple Silicon 上的推論吞吐量已經比 llama.cpp 高 21%-87%。oMLX 在這個基礎上再加分層 KV cache，在多輪 agent 場景下的體驗差距就更大了。

---

## 跟 Ollama、LM Studio 比，到底選誰

![omlx-competition-comparison](https://hackmd.io/_uploads/HyPgPf7qWe.jpg)

這是大家最想知道的問題。直接上表：

| 特性 | oMLX | Ollama | LM Studio |
|------|------|--------|-----------|
| **推論後端** | MLX 原生 | llama.cpp (GGUF) | llama.cpp + MLX |
| **KV Cache 持久化** | SSD 分層 | 無 | 無 |
| **Continuous Batching** | 有 | 無 | 部分 |
| **API 格式** | OpenAI + Anthropic | OpenAI | OpenAI |
| **Coding Agent 整合** | 一鍵設定 | 手動 | 手動 |
| **MCP 工具** | 有 | 無 | 無 |
| **跨平台** | macOS only | 全平台 | 全平台 |
| **GUI** | Menu Bar + Web | CLI | 桌面應用 |
| **模型格式** | MLX safetensors | GGUF | GGUF + MLX |

怎麼選？其實很簡單：

**用 Mac + 跑 coding agent = oMLX。** SSD KV cache 在這個場景下是不可取代的優勢，其他工具做不到。

**需要跨平台或 NVIDIA GPU = Ollama / LM Studio。** oMLX 只吃 Apple Silicon，不吃別的。

**想要最簡單的上手體驗 = LM Studio。** GUI 做得最好，適合入門。

**想要極致控制 = Ollama。** 純 CLI，Docker 友善，伺服器場景首選。

---

## 30 天 30 個版本：這個開發速度有點誇張

![omlx-rocket-growth](https://hackmd.io/_uploads/HyMZPf7qZg.jpg)

oMLX 在 2026 年 2 月 13 日上線。到我寫這篇文章的今天（3 月 15 日），已經發了 30 個 release。

沒有打錯，**幾乎每天一版。**

光看最近一週的更新就很驚人——Agent session stall 修復、M5 Neural Accelerator 支援、Qwen3-Reranker 整合、OpenAI Responses API、繁體中文 locale（台灣開發者 @JianShan-1214 貢獻的）、8GB 裝置支援修復、[oMLX.ai 效能比較平台](https://omlx.ai/)上線，社群已經提交了近一萬筆 benchmark 數據。

但說實話，這種開發節奏也讓我有點緊張。

---

## 踩坑紀錄：這些問題你會遇到

快速迭代的另一面就是穩定性還在路上。從 GitHub Issues 和社群回報整理幾個已知的坑：

**Context Compacting 導致模型遺失（#230）**——多輪對話後，context 壓縮機制偶爾會觸發模型狀態丟失。如果你發現 agent 突然「失憶」，很可能是這個問題。

**Tool Call Streaming 洩漏（#159, #172, #174）**——Claude Code 使用時，tool call 的封裝標記 `[Tool call: ...]` 有時會作為純文字洩漏到輸出中，造成對話卡住。v0.2.8 和 v0.2.9 陸續修了好幾波，但邊界情況可能還有。

**VLM 位置編碼汙染（#131）**——如果第一個請求包含圖片，第二個純文字請求可能輸出亂碼。原因是 mRoPE position state 沒清乾淨。v0.2.8 已修復。

**8GB 裝置完全無法載入模型（#137）**——原本的 `max_model_memory: auto` 會固定保留 8GB 給系統，8GB 機器等於零可用。v0.2.10 改成百分比制解決。

> **踩坑提醒**：如果你用 Homebrew 安裝遇到 pydantic-core dylib fixup failure，那是因為 bundled wheel 的動態連結庫有問題。v0.2.8 之後改為從原始碼編譯 pydantic-core。

---

## 快速上手：從安裝到跑起來

> **前置條件**
> - macOS 15.0+（Sequoia 或 Tahoe）
> - Apple Silicon（M1 / M2 / M3 / M4 / M5）
> - 16GB RAM 最低需求，64GB+ 建議
> - Python 3.10+（僅原始碼安裝需要）

三種安裝方式，選最適合你的：

```bash
# 方法一：DMG（最快，推薦一般用戶）
# 從 https://github.com/jundot/omlx/releases 下載
# M5 用戶務必選 macos26-tahoe 版本

# 方法二：Homebrew
brew tap jundot/omlx https://github.com/jundot/omlx
brew install omlx

# 方法三：原始碼安裝（開發者用）
git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e ".[mcp]"   # 包含 MCP 支援
```

啟動伺服器：

```bash
# 基本啟動
omlx serve --model-dir ~/models

# 完整設定：啟用 SSD cache + 記憶體限制 + batch 調優
omlx serve \
  --model-dir ~/models \
  --paged-ssd-cache-dir ~/.omlx/cache \
  --max-process-memory 80% \
  --prefill-batch-size 8 \
  --completion-batch-size 32
```

接上 Claude Code：

```bash
# 方法一：Admin Dashboard 一鍵設定
# 打開 http://localhost:5050/admin → Integrations → Claude Code

# 方法二：手動設定
export ANTHROPIC_BASE_URL=http://localhost:5050/v1
```

如果你已經有 [LM Studio](https://lmstudio.ai/) 下載的模型，可以直接把 `--model-dir` 指向 LM Studio 的模型目錄，oMLX 會自動偵測。

---

## 該不該現在就用

我的看法很直接。

如果你是 Mac 用戶，重度使用 Claude Code 或類似的 coding agent，而且受夠了每輪等一分鐘的推論延遲——現在就試。SSD KV cache 的體驗差距是量級上的，不是微調等級的改善。

但如果你需要穩定的生產環境，再等等。這個專案才一個月大，Issues 裡還有系統崩潰（#234）和 context 遺失（#230）這種等級的問題。單一維護者主導的專案，長期可持續性也是個問號——雖然社群貢獻正在快速增長。

我會建議在非關鍵的開發場景先用起來，等 v0.3.x 穩定之後再考慮更正式的使用。

這個專案填補了一個非常精確的市場空白。不是更快的推論引擎（那是 MLX 本身的功勞），而是**讓本地推論在 agent 場景下真正可用的那最後一塊拼圖**。有時候，改變遊戲規則的不是什麼 breakthrough，只是有人看到了一個所有人都忽略的問題，然後用最直覺的方式解決它。

把 KV cache 存到 SSD 上。就這麼簡單。

---

## 延伸閱讀

- [GitHub: jundot/omlx](https://github.com/jundot/omlx) — 原始碼與文件
- [oMLX.ai](https://omlx.ai/) — 官網與社群 benchmark 資料庫
- [Hacker News: Show HN 討論串](https://news.ycombinator.com/item?id=47247294) — 作者與社群的技術問答
- [vllm-mlx 研究論文](https://arxiv.org/abs/2511.05502) — Apple Silicon 推論效能研究
- [Reddit: r/LocalLLaMA oMLX 討論](https://www.reddit.com/r/LocalLLaMA/comments/1r3qwyi/) — 社群使用回饋
- [Ken Huang: 本地跑 35B Coding Agent](https://kenhuangus.substack.com/p/i-ran-a-35b-ai-coding-agent-locally) — 實戰經驗分享