oMLX 是为 Apple Silicon 量身定做的推理服务器，因此它对运行环境有硬性要求，开工前先逐条核对。

1. 芯片与平台——必须是 Apple Silicon，覆盖 M1／M2／M3／M4／M5；Intel Mac 不在支持范围内。
2. 操作系统——macOS 15.0 及以上（Sequoia）。
3. Python 版本——3.11 至 3.13；若走源码安装或需要构建自定义内核，还要装完整的 Xcode（仅 Command Line Tools 不够，缺 Metal 工具链）。
4. 模型准备——oMLX 加载 MLX 格式的模型，可直接在管理后台一键从 HuggingFace 搜索下载，无需事先手动准备。

官方提供三条安装路径，功能定位略有差异，按需选一条即可。下面从最省心的图形化方式讲起。

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

# 升级到最新版
brew update && brew upgrade omlx

# 作为后台服务运行（崩溃自动重启）
omlx start

# 可选：安装 MCP（Model Context Protocol）支持
/opt/homebrew/opt/omlx/libexec/bin/pip install mcp

brew install jundot/omlx/omlx --HEAD --with-custom-kernel

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e .          # 仅核心
pip install -e ".[mcp]"   # 带 MCP 支持

OMLX_WITH_CUSTOM_KERNEL=1 pip install -e .

理解 oMLX 为什么「好用」，要看它解决的是什么问题。作者在 README 开头的一段自述，把动机讲得很直白（原文为英文，此处保留关键句）：他试过的每个 LLM 服务器都逼他在「方便」和「可控」之间二选一；他想把常用模型常驻内存、更重的模型按需换入、并且能设上下文上限，还全部在菜单栏管理。

他给出的答案是：oMLX 让 KV 缓存在热的内存层与冷的 SSD 层之间持久化——即使对话中途上下文发生变化，历史上下文仍然保持缓存、并跨请求复用，这让本地 LLM 配合 Claude Code 这类工具做真实编码工作变得可行。 换句话说，oMLX 的价值不在「让模型跑得更快一秒」，而在「让重复的上下文不必每次重算」。

具体到实现，这套分层缓存借鉴了 vLLM 的思路，采用基于块（block-based）的 KV 缓存管理，支持前缀共享与写时复制（Copy-on-Write），分两层协作：

• 热层（RAM）——高频访问的缓存块留在内存里，读取最快。
• 冷层（SSD）——热缓存写满后，块以 safetensors 格式下沉到 SSD；下一次请求若前缀命中，直接从磁盘恢复，而不是从头重算——即便服务器重启后依然有效。

与分层缓存配套的是连续批处理：并发请求通过 mlx-lm 的 BatchGenerator 统一调度，最大并发数可在 CLI 或管理面板配置。两者叠加，才让「一台 Mac 常驻多个模型、边聊边复用」成为日常。

装好之后，oMLX 提供三种运行形态，覆盖从「点了就用」到「常驻后台」的不同需求。

1. 菜单栏管理——原生 Swift / SwiftUI 菜单栏 App（非 Electron）。不打开终端就能启停、监控服务，附带本地用量历史、按小时热力图、跨重启常驻的服务统计、崩溃自动重启与内置自动更新。
2. 前台附着终端运行——用 omlx serve --model-dir ~/models，进程直接跑在当前终端里，日志实时可见，适合调试与首次体验。
3. 托管后台服务——用 omlx start／omlx stop／omlx restart 作为可移植的生命周期命令；Homebrew 安装会把它委托给 brew services，崩溃自动重启。

后台服务默认零配置运行：模型目录 ~/.omlx/models、端口 8000。日志分两处：服务日志在 $(brew --prefix)/var/log/omlx.log（stdout/stderr），结构化服务器日志在 ~/.omlx/logs/server.log。想自定义，设环境变量（如 OMLX_MODEL_DIR、OMLX_PORT），或先手动跑一次 omlx serve --model-dir /your/path 把设置持久化到 ~/.omlx/settings.json。

除了缓存与调度这条主线，README 的 Features 章节还列出了一批配套能力。以下择要介绍，均为官方已写明的功能。

API 层是 OpenAI 与 Anthropic 的即插即用替代，主要端点如下：

* 端点与能力均取自 README「API Compatibility」章节；工具调用与结构化输出也受支持，需模型的 chat template 接受 tools 参数。

装完别急着用，先花两分钟确认关键能力真的到位，尤其是那个会「静默回退」的自定义内核坑。

1. 确认服务在跑——浏览器打开 http://localhost:8000/admin 能看到后台，或连 http://localhost:8000/v1 有 OpenAI 兼容响应，即说明加载成功。
2. 验证内核是否构建——若你服务 GLM-5.2 / MiniMax M3 / Qwen3.5，用下面这行核对原生内核状态。

python -c "from omlx.custom_kernels import native_kernel_status; print(native_kernel_status())"