Ejecutar agentes de codificación locales en una Mac con oMLX: Explicación del caché KV respaldado en disco

Después de doce minutos de una sesión de programación, el modelo local deja de comportarse como un agente y comienza a actuar como una máquina de fax. Las primeras llamadas a las herramientas se respondían en dos segundos. Ahora cada turno tarda treinta, a veces noventa. La tarea no ha cambiado; simplemente el contexto se ha alargado, y el servidor local vuelve a calcular toda la conversación desde cero con cada solicitud.

Ese síntoma, los tiempos de inicio lentos y no la lentitud en el procesamiento de tokens, es precisamente lo que se buscó eliminar con un pequeño proyecto basado en Apple Silicon llamado oMLX. No se trata de un modelo ni de un agente, sino de un servidor de inferencia con una promesa concreta: todo lo que el agente ya ha leído se mantiene en caché, incluso a medida que la sesión crece, de modo que el turno doce se siente como el turno uno. La prueba real no es una demostración llamativa, sino su comportamiento en el turno cuarenta de una sesión de trabajo real, en el hardware que realmente posees.

Por qué las Macs tienen dificultades con los agentes de programación

Sobre el papel, Apple Silicon es una plataforma sólida para la inferencia local. La memoria unificada proporciona un único conjunto de recursos tanto para la CPU como para la GPU, de modo que un modelo cuantizado se almacena en la RAM sin necesidad de utilizar el bus, y el framework MLX de Apple fue diseñado específicamente para este tipo de cargas de trabajo.

Los problemas surgen cuando las conversaciones se convierten en tareas realizadas por agentes. Un agente de programación vuelve a leer casi todo su contexto anterior en casi cada turno, llama a una herramienta, recibe el resultado añadido al prompt y repite este proceso decenas de veces. El prefijo, que representa la parte inicial compartida del prompt, coincide casi por completo con el del turno anterior, salvo por un nuevo resultado de herramienta al final.

La mayoría de los servidores locales interpretan esa coincidencia parcial como una falta total de coincidencia, descartan la caché clave-valor y vuelven a calcular desde cero. En una solicitud breve nadie se da cuenta. Pero en una sesión de 20,000 tokens, esto hace que una respuesta de dos segundos difiera significativamente de una de noventa segundos. El creador del proyecto mencionó precisamente esto como motivo en el foro de discusión de MLX de Apple: los agentes de programación envían solicitudes cuyos prefijos cambian, y cada servidor MLX existente invalida la caché y vuelve a calcular todo cuando eso ocurre.

Qué es oMLX

oMLX es un servidor de inferencia de código abierto basado en MLX y mlx-lm de Apple. Se distribuye como una aplicación nativa de la barra de menús de macOS y también como una herramienta de línea de comandos en Python. Fue creado por un desarrollador llamado Jun Kim y se encuentra en GitHub bajo el nombre jundot/omlx, con licencia Apache 2.0. En el momento de escribir esto, contaba con aproximadamente 18,600 estrellas, 1,600 forks y más de dos mil commits.

Nada de eso demuestra fiabilidad. Las estrellas miden la atención y no la madurez, y un proyecto que publica varios candidatos a versión al mes todavía está encontrando su equilibrio. La popularidad es una razón para probarlo, no un sustituto de las pruebas.

Un único proceso sirve para dos estilos de API: completaciones de chat compatibles con OpenAI y una ruta nativa de estilo Anthropic /v1/messages, junto con rutas para completaciones, embeddings y reclasificación. Puede mantener cargados modelos de lenguaje, modelos de lenguaje y visión, modelos OCR y herramientas de reclasificación al mismo tiempo, con eliminación por LRU y fijación por modelo. Para los agentes, lo importante es lo que ocurre debajo de esa superficie.

Los prefijos se guardan en el disco, no en la memoria temporal

La inferencia básica de MLX almacena en la memoria de la GPU solo el caché de una conversación mientras el prefijo siga coincidiendo. La apuesta central de oMLX es un caché de dos niveles que resiste tanto la deriva del prefijo como los reinicios. Los bloques de uso frecuente permanecen en un nivel activo de la memoria. Cuando este se llena, los bloques se escriben en un nivel inactivo en un SSD en formato safetensors, gestionándose bloque por bloque mediante el intercambio de prefijos y la copia al escribir. Si una solicitud posterior coincide con un prefijo que fue guardado en disco, esos bloques se leen de nuevo y no se vuelven a calcular.

Un bibliotecario que nunca vuelve a colocar en estantes un libro que recientemente prestaste es una imagen adecuada. Pídelo de nuevo más tarde, incluso después de que la biblioteca vuelva a abrir, y el libro ya estará en el mostrador.

Un SSD no es RAM, por lo que restaurar una caché grande sigue tomando tiempo real, aunque eso es mucho más económico que volver a calcular cada token. La ventaja es mayor para el patrón de agente descrito anteriormente: prefijos largos, en su mayoría repetidos, con un pequeño cambio al final. El servidor también realiza procesamiento por lotes continuo a través de BatchGenerator de mlx-lm, atendiendo solicitudes concurrentes en lugar de ponerlas en cola, y el nivel de este proceso se puede configurar desde la línea de comandos o el panel de administración.

Hay dos números que son los más importantes. El tiempo hasta el primer token indica cuánto tarda en llegar algo. La velocidad de generación indica cuán rápido llegan los tokens una vez que comienzan a generarse. La reutilización de la caché se aplica después del primer token y deja el segundo sin tocar. Un modelo que genera lentamente seguirá generando lentamente, pero comenzará a responder antes.

Instalación en Apple Silicon

Los requisitos son macOS 15 (Sequoia) o una versión más reciente, Python entre 3.11 y 3.13, y un chip de las familias M1, M2, M3 o M4. Existen tres opciones, y la primera es la más adecuada para la mayoría de las personas.

La opción recomendada es la aplicación para macOS. Descargue el archivo .dmg firmado y notariado desde GitHub Releases, arrástrelo a Applications y ábralo. Una pantalla de bienvenida guiará en la selección del directorio del modelo, iniciará el servidor y la primera descarga, y la aplicación instalará un pequeño complemento de línea de comandos.

Con Homebrew:

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

De la fuente:

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

Quienes planeen utilizar GLM-5.2, MiniMax M3 o Qwen3.5 deben saber que una simple instalación con pip omite sus kernels personalizados nativos, y los modelos afectados recorren entonces silenciosamente un camino mucho más lento. El proyecto indica que su kernel prefill fusionado es aproximadamente 30 veces más rápido en un M3 Ultra para uno de ellos. Para generar los kernels se necesita Xcode completo y no solo las Herramientas de Línea de Comandos, lo cual es el argumento más sencillo a favor del formato DMG.

Antes de conectar cualquier dispositivo, confirme que el servidor está activo:

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

Está bien tener una lista vacía si aún no se ha definido ningún directorio de modelos.

Cargando el primer modelo

oMLX detecta automáticamente modelos de lenguaje, modelos de lenguaje y visión, modelos de embedding y herramientas de reclasificación en el directorio al que está apuntado. También lee directamente un caché existente de Hugging Face y una carpeta de LM Studio, por lo que no es necesario descargar nada dos veces.

omlx serve --model-dir ~/models

El modelo debe adaptarse al tamaño de la memoria de la máquina, no al archivo más grande disponible. Deje cuatro o cinco gigabytes de espacio libre en macOS y destine el resto a los pesos del modelo más al crecimiento del caché. Un modelo de 9 mil millones de parámetros en formato de 4 bits es adecuado para máquinas con 16 a 32 GB de memoria. Los modelos de la categoría de 30 a 40 mil millones de parámetros requieren 64 GB o más. Los modelos más grandes, según las pruebas propias del proyecto, necesitan una memoria en el Mac Studio superior a los 400 GB.

Los modelos se pueden descargar desde el navegador de Hugging Face integrado en el panel de administración en http://localhost:8000/admin, o mediante cualquier flujo de descarga hf existente dirigido al directorio del modelo. Una solicitud básica se parece a una solicitud normal de completación de chat en OpenAI:

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."}]}'

Si se recibe una respuesta de finalización, el endpoint funciona.

Conexión de Claude Code, Codex, Cursor y OpenCode

Existen dos formas en las que oMLX se conecta con los agentes, y la que se utiliza depende de cómo almacena el agente su configuración, no de cuán bien esté soportado.

Herramientas con archivo de configuración

OpenClaw, OpenCode, Codex y Pi leen un archivo de configuración al que oMLX puede acceder directamente: JSON para los dos primeros y TOML para Codex. Los adaptadores de integración escriben en ese archivo, y la pestaña Integrations del panel de administración envía una única orden:

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

Al ejecutarlo, se actualiza la configuración de la herramienta y se inicia el agente en un solo paso. Primero se hace una copia de seguridad de toda configuración existente como un archivo .bak con marca de tiempo, para que sea posible revertir los cambios si algo no funciona correctamente.

Hermes Agent y la opción Copilot

Ambos aparecen en la lista de un clic del README, y la propia documentación de Hermes Agent lo confirma por separado: el asistente de configuración cuenta con una opción de endpoint personalizado compatible con OpenAI para dirigirse a cualquier servidor local, incluido oMLX. Para omitir el panel de control, diríjalo manualmente a http://localhost:8000/v1.

La opción Copilot merece ser revisada detenidamente antes de que alguien confíe en ella. El verdadero Copilot Chat de GitHub se autentica mediante OAuth contra api.githubcopilot.com y no está diseñado para aceptar una URL base local arbitraria. Por lo tanto, la integración de Copilot con un solo clic apunta o bien a una herramienta diferente con el mismo nombre o bien utiliza un mecanismo que la documentación pública no confirma. Verifique directamente la pestaña Integraciones antes de asumir que hace lo que indica su nombre.

Claude Code

Claude Code obtiene su dirección del servidor desde la variable de entorno ANTHROPIC_BASE_URL al iniciar, y no de un archivo que oMLX pueda editar, por lo que este proceso sigue siendo manual. Dado que oMLX sirve la ruta nativa /v1/messages, no se necesita un proxy de traducción:

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 también incluye funcionalidades diseñadas específicamente para Claude Code. Los informes de escalamiento de contexto muestran el recuento de tokens para que la compresión automática se active correctamente en una ventana de contexto local más pequeña, y la función SSE keep-alive evita los tiempos de espera al leer durante un prefill prolongado. Se trata de detalles reales específicos del agente y no de una casilla de compatibilidad genérica.

Cursor

La configuración de modelo local de Cursor se encuentra dentro de su interfaz gráfica, por lo que no existe ningún archivo al que oMLX pueda escribir. En Ajustes, bajo Modelos, busca la sección API de OpenAI y activa el interruptor Override Base URL. Cursor ha cambiado el nombre de ese interruptor en ocasiones anteriores, por lo que la etiqueta puede variar según la versión. Introduce http://localhost:8000/v1 y escribe cualquier cadena que no esté vacía en el campo de clave API, ya que un servidor en localhost no la verifica. Añade el modelo cargado bajo Modelos personalizados con su nombre exacto tal como aparece en oMLX, y desactiva los modelos predeterminados de Cursor para que no intente validarlos también contra los servidores de OpenAI.

Verificar que realmente funciona

Durante una sesión real, los paneles de caché caliente y frío del panel de administración deben seguir acumulando bloques y no reiniciarse en cada turno. Un reinicio en cada turno suele significar que el contenido de los mensajes del sistema o de los esquemas de herramientas se está reordenando entre las llamadas, lo cual rompe el prefijo.

Medición entre caché caliente y frío

En lugar de repetir como hecho una afirmación del proveedor, se puede realizar una prueba localmente. Corrija el modelo, la cuantización, la longitud de contexto y los mensajes de inicio en todas las herramientas, y luego registre el tiempo de inicio en frío, el tiempo en frío hasta el primer token, el tiempo en caliente hasta el primer token con un prefijo repetido, la velocidad constante de generación, el consumo máximo de memoria, el comportamiento después de 15 a 20 turnos simulados del agente, el tiempo de configuración y si las llamadas a las herramientas siguen siendo interpretadas correctamente durante toda la sesión.

Las cifras publicadas por el propio proyecto, obtenidas con un M3 Ultra de 512 GB y claramente de fabricante original, muestran una generación de entre 45 y 59 tokens por segundo para Qwen3-Coder-Next de 8 bits en contextos que van de 1k a 32k. El procesamiento en lotes continuos logra una aceleración de aproximadamente 4,14 veces en ocho solicitudes simultáneas frente a una sola. Eso representa un límite superior para hardware de alta gama y no es lo que obtendrá un MacBook Air de 16 GB.

Un informe independiente indica que un contexto de 8,700 tokens tomó unos veinte segundos con MLX estándar, mientras que la respuesta desde la caché caliente llegó tan rápidamente que el autor volvió a realizar la prueba para asegurarse. Se trata de un relato de terceros y no de una prueba controlada, por lo que vale la pena reproducirla antes de confiar en ella.

El tiempo de arranque en frío hasta el primer token no difiere significativamente del MLX en estado bruto, ya que aún no hay nada que reutilizar. Todo el beneficio radica en las interacciones con prefijo repetido en modo activo, que constituyen la mayor parte de una sesión de un agente de programación.

Operación del servidor

Arranque, detención y reinicio, con la variante en primer plano conectada a la terminal:

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

Confirme que está en ejecución y sirviendo un modelo:

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

Evita que el uso de memoria interfiera con el resto del sistema:

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

Ajuste la caché de dos niveles directamente:

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

Aumenta la concurrencia cuando varios agentes acceden al servidor al mismo tiempo:

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

Las instalaciones de Homebrew siguen el mismo ciclo de vida a través de brew services:

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

Leer más

• Por qué los agentes de larga duración necesitan una máquina de estados: roles de líder, trabajador y verificador — Cuatro formas en que un único bucle de agente falla en tareas prolongadas, y cómo un equipo de líder, trabajador y verificador impulsado por un motor determinista las soluciona, además de cuándo omitirlo.
• Ocho bases de datos vectoriales gratuitas para agentes de IA comparadas: limitaciones, adecuación y compromisos — Comparación de ocho bases de datos vectoriales con planes gratuitos para la memoria de los agentes: límites estrictos, adecuación para el despliegue, concurrencia y cuál elegir para su entorno.