如何使用 MLX Harness。

1安装 MLX Harness

你需要一台搭载 Apple 芯片、运行 macOS 14.5 或更高版本的 Mac。推理引擎内置于 App 中，无需另外安装：下载后把 MLX Harness 移到“应用程序”文件夹并打开即可。

MLX Harness 是 JANGQ AI 的 vMLX 的修改版，以 Apache License 2.0 发布。底层引擎就是 vMLX 的引擎，未作改动；MLX Harness 修改的是引擎外层的 App，并加入了 Network 页面。

2选择并下载模型

模型来自 Hugging Face，大多是 mlx-community 组织发布的 MLX 格式模型。下载前先看看哪些装得下：Compare 会显示你的 Mac 内存能容纳哪些模型，以及每个模型大致的生成速度。

1. 打开 Models，选择 Find & download。搜索后可按下载量、热度、点赞数、最近更新或模型大小排序；搜索结果列出的是 MLX 模型。
2. 点按一个模型阅读它的 README，然后下载。下载在后台进行，Downloads 会显示进度。
3. 对于 Llama 等受限模型，先在 HF Token: 栏中填入你的 Hugging Face 令牌，并在 huggingface.co 上接受该模型的许可。
4. Library & tools 列出你 Mac 上的模型。Inspect Model 显示模型的元数据，Diagnose Model 运行健康检查，Convert Model 把 Hugging Face 模型转换为量化的 MLX 模型：Balanced (4-bit)、Quality (8-bit) 或 Compact (3-bit)。

下载内容默认存入你的 Hugging Face 缓存文件夹，也可以在 Download to: 下另选位置。MLX Harness 还会找到已在该缓存中、在 ~/.mlxstudio/models 中，以及在你于 Directories 下添加的文件夹中的模型。

3聊天与图像

聊天与推理

1. 打开 Chat & Images，在聊天工具栏的模型菜单中选择一个模型，或选 Add local model。它会以检测到的默认设置启动；高级选项保留在 Servers & API 中。
2. 输入消息。推理模型会把思考过程显示在单独的框中。聊天设置中的 Enable Thinking 可设为 Auto、On 或 Off，Reasoning Effort 为支持的模型设置推理深度。
3. 视觉模型可以接收图像：把文件拖到聊天中，或使用附件按钮。接受视频、音频和文本文件的模型也能处理这些文件。
4. 聊天记录保存在侧边栏中，可以搜索。设置按模型分别保存。

你也可以和别处的模型聊天：Connect remote endpoint 可以填入任何兼容 OpenAI 的 API 地址。只有这时，你的提示词才会离开 Mac。

生成和编辑图像

在 Chat & Images 中选择 Image。图像模型通过 mflux 运行，图像服务器从你 Mac 上的一个文件夹载入模型：Find mflux models 会在 Models 中打开图像模型搜索，然后用 Load selected folder 启动。

部分图像模型（例如 Flux Dev）在 Hugging Face 上受限，需要你的令牌并接受许可后才能下载。

4智能体与工具

MLX Harness 可以让模型在你的 Mac 上执行操作。在聊天设置中开启 Enable Built-in Coding Tools 并选择一个 Working Directory：所有文件操作和命令都在其中运行。然后按类别开启或关闭工具：

Max Tool Iterations 限制一条消息最多可以进行多少轮工具调用（默认 10 轮）。Shell 和文件工具操作的是真实文件，所以请把工作目录指向某个项目，而不是你的主文件夹，并使用你信得过的模型。

5从其他 App 使用：本地 API

你启动的每个模型都在你的 Mac 上提供服务。位于 http://localhost:8080 的 API Gateway 按请求中的模型名称把每个请求转给对应的模型，被请求时还会启动已停止的模型。每个模型也有自己的端口，从 8000 起。默认只有你的 Mac 能访问它们；开启 LAN 后，它们会向你的局域网开放。

在 API 背后，引擎会缓存它已经读过的内容。开启 Continuous Batching 后，Prefix Cache 能让长对话或编程智能体反复出现的指令在下一轮跳过重复计算，KV Cache Quantization 会压缩这份缓存，Disk Cache (Persistent) 则把它保存在 SSD 上。这些选项都在每个模型的服务器设置中。

一个 OpenAI 格式的请求，使用 API 页面显示的模型名称：

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR-MODEL",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

任何 OpenAI SDK 都可以使用，只需把 base_url 设为 http://localhost:8080/v1；除非你为会话设置了密钥，否则密钥可以是任意文本。对于编程智能体，Coding Tool Integration 可以通过 Auto-Configure 为 Claude Code、Codex CLI、OpenCode、OpenClaw 和 Hermes Agent 完成设置，或显示 Manual Setup。以 Claude Code 为例，就是把以下内容合并进 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8080",
    "ANTHROPIC_MODEL": "YOUR-MODEL",
    "ANTHROPIC_API_KEY": "mlxstudio"
  }
}

6Network 页面与 MLX Node

Network 显示来自 mlx.app 的 MLX Network 实时数据：在线和正在工作的 Mac、每秒 token 数、今日 AI token 数和国家数。它会检查这台 Mac 是否安装并运行了 MLX Node，并能打开它或链接到下载。在 Your wallet 下输入你的钱包名称并按 Show，就能看着它挖得的 MLX 实时增长；这个名称只保存在这台 Mac 上。

MLX Harness 本身从不挖矿，它为你运行模型。MLX Node 是另一款菜单栏 App，把你 Mac 的闲置时间借给 MLX Network 并赚取 MLX 代币：免费席位每天最多 1 MLX，锁定 30 天。如果两者都用，它们会共享同一块内存和 GPU，所以 MLX Node 的 Memory MLX may use 上限以及手动的开始和停止，能让它不妨碍你。MLX 代币可能贬值；请阅读风险提示。

7常见问题

MLX Harness 免费吗？

免费。它和其所基于的项目 vMLX 一样，采用 Apache License 2.0 许可证。

什么时候可以下载 MLX Harness？

现在就可以。它可在 harness.mlx.app 和 mlx.app/download 免费下载，适用于运行 macOS 14.5 或更高版本的 Apple 芯片 Mac。源代码在 GitHub 上：github.com/MLXapp/studio。

MLX Harness 能在哪些 Mac 上运行？

搭载 Apple 芯片（M1 或更新）、运行 macOS 14.5 或更高版本的 Mac。你的 Mac 内存决定能装下哪些模型；mlx.app 上的 Compare 会把它们列出来。

MLX Harness 会把我的提示词发到别处吗？

不会。本地模型在你的 Mac 上运行，除非你开启 LAN，否则 API 只在你的 Mac 上监听。只有在你连接远程端点时，提示词才会离开 Mac。

MLX Harness 能赚取 MLX 代币吗？

不能。MLX Harness 为你运行模型，只读取公开的网络数据。为 AI 工作赚取 MLX 代币的是 MLX Node。