OpenCode / Claude Code + MLX - Un assistant codeur local sur votre Mac (Patreon)
Content
Si vous avez un Mac Apple Silicon, sachez que OpenCode peut utiliser un LLM servi en local par MLX. J'ai découvert ça grâce à Awni Hannun, l'un des créateurs de MLX, qui a publié le montage de base dans un gist. J'ai repris et j'ai poussé l'idée jusqu'à Claude Code avec notamment Qwen3.6-27B. Je l'ai testé sur mon MacStudio M4 Max et ça marche du feu de dieu, même si ça reste un peu lent !! Après y'a quand même des petits pièges à connaitre donc je vous fait un petit tuto pour faire tout pareil chez vous.
Faut savoir que MLX c'est super cool parce que ça exploite directement la mémoire unifiée et le GPU du Mac. C'est donc très efficient. Pour les besoins de ce tutoriel, j'ai utilisé le modèle leonsarmiento/Qwen3.6-27B-3bit-mlx, qui pèse seulement 12,1 Go, et qui utilise une quantification mixte 3-bit/5-bit.
Allez, c'est parti mon kiki ! Comme d'habitude, désolé pour la mise en page du code. Sur Patreon, il n'y a pas de style "code" alors je me contenterais de mettre ça en italique.
Étape 1 - Installer dans un environnement isolé
On commence par ça :
curl -fsSL https://opencode.ai/install | bash
python3 -m venv "$HOME/.venvs/mlx-code"
source "$HOME/.venvs/mlx-code/bin/activate"
Enfin, pour OpenCode avec MLX :
python -m pip install -U mlx-lm
Et uniquement si vous voulez aussi utiliser le pont vers Claude Code :
python -m pip install -U 'litellm[proxy]'
Le supplément [proxy] est important car sans lui, LiteLLM peut s'arrêter net dès le lancement sur une dépendance manquante.
Étape 2 - Lancer MLX
Ensuite on lance le serveur MLX :
mlx_lm.server
Le serveur écoutera alors sur 127.0.0.1:8080. Il ne charge rien tout de suite car le nom du modèle arrive avec la première requête, puis les 12,1 Go sont téléchargés s'ils ne sont pas déjà dans le cache Hugging Face.
Pour vérifier que le serveur est actif, faites :
curl http://127.0.0.1:8080/v1/models
Dans une session macOS isolée ou certains bacs à sable, MLX peut répondre qu'aucun périphérique Metal n'est disponible. Lancez alors le serveur depuis un Terminal normal sur le Mac.
Étape 3 - Brancher OpenCode
Maintenant que notre serveur tourne, on va le configurer avec OpenCode.
Créez ~/.config/opencode/opencode.json avec ça dedans :
{
"$schema": "https://opencode.ai/config.json",
"model": "mlx/leonsarmiento/Qwen3.6-27B-3bit-mlx",
"provider": {
"mlx": {
"npm": "@ai-sdk/openai-compatible",
"name": "MLX (local)",
"options": {
"baseURL": "http://127.0.0.1:8080/v1",
"apiKey": "none"
},
"models": {
"leonsarmiento/Qwen3.6-27B-3bit-mlx": {
"name": "Qwen3.6 27B local",
"limit": {
"context": 262144,
"output": 32768
}
}
}
}
}
}
Cette version sélectionne directement le modèle et fournit une fausse clé locale. Pas besoin comme ça de passer par /connect dans le CLI. Lancez simplement opencode dans votre projet.
Ensuite, lancez opencode et faites quelques tests en lui demandant par exemple de vous coder un Tetris en Rust et de le compiler.
Vous verrez que le tool calling fonctionne à merveille, par contre, selon votre machine, ce sera plus ou moins long. Par exemple, pour moi, cette première session a consommé 65 192 token et a pris +5 min avant de lancer le lancer le premier outil. Ensuite, ça sera beaucoup plus rapide car le modèle sera chargé en mémoire.
Étape 4 - Utiliser le modèle local dans Claude Code
Claude Code ne sait pas communiquer directement avec mlx_lm.server car les deux logiciels n’utilisent pas le même format d’API. Il faut donc placer LiteLLM entre les deux :
Claude Code -> port 4000 -> LiteLLM -> port 8080 -> MLX et Qwen3.6
Vous aurez trois terminaux ouverts :
MLX fait tourner le modèle.
LiteLLM traduit les requêtes.
Claude Code envoie ses demandes à LiteLLM.
Terminal 1 - Vérifier que MLX fonctionne
Le serveur MLX lancé précédemment doit toujours tourner et si vous avez lancé MLX sur un autre port, remplacez 8080 dans toutes les commandes suivantes (comme ce que.
Terminal 2 - Installer LiteLLM
Activez l’environnement Python créé au début du tutoriel.
Créer le fichier de configuration LiteLLM
Créez un dossier pour sa configuration :
mkdir -p "$HOME/.config/litellm"
Ouvrez ensuite un nouveau fichier avec Nano :
nano "$HOME/.config/litellm/config.yaml"
Collez ceci dedans :
model_list:
- model_name: claude-qwen-local
litellm_params:
model: openai/leonsarmiento/Qwen3.6-27B-3bit-mlx
api_base: http://127.0.0.1:8080/v1
api_key: none
drop_params: true
general_settings:
master_key: sk-local
Dans Nano, enregistrez avec Ctrl + O, validez avec Entrée, puis quittez avec Ctrl + X.
Je vous explique les paramètres. model_name c'est le nom que Claude Code verra. Ensuite il y a model qui est le véritable modèle chargé par MLX, api_base est l’adresse du serveur MLX, master_key protège le proxy LiteLLM avec la clé locale sk-local et enfin drop_params retire les paramètres Anthropic que MLX ne comprend pas.
Attention à l’emplacement de master_key. Il doit être placé dans general_settings, exactement comme ci-dessus.
Lancer LiteLLM
Toujours dans le deuxième terminal, activez le mode de compatibilité nécessaire :
export LITELLM_USE_CHAT_COMPLETIONS_URL_FOR_ANTHROPIC_MESSAGES=true
Lancez ensuite le proxy :
litellm --config "$HOME/.config/litellm/config.yaml" --host 127.0.0.1 --port 4000
Laissez ce terminal ouvert.
La variable LITELLM_USE_CHAT_COMPLETIONS_URL_FOR_ANTHROPIC_MESSAGES oblige LiteLLM à utiliser la route /v1/chat/completions comprise par MLX et sans elle, vous risquez une erreur 404 sur /v1/responses.
Pour vérifier le proxy depuis un troisième terminal :
curl -H "Authorization: Bearer sk-local" http://127.0.0.1:4000/v1/models
La réponse doit contenir :
claude-qwen-local
Terminal 3 - Lancer Claude Code
Dans le troisième terminal, indiquez à Claude Code qu’il doit utiliser LiteLLM au lieu de l’API Anthropic :
export ANTHROPIC_BASE_URL="http://127.0.0.1:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local"
export ANTHROPIC_MODEL="claude-qwen-local"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-qwen-local"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS="1"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
Lancez ensuite Claude Code dans votre projet :
claude
ANTHROPIC_MODEL est important car sans cette variable, Claude Code peut continuer à demander son modèle habituel, par exemple claude-opus-4-8 et LiteLLM ne le connaît pas puisqu’il expose uniquement claude-qwen-local, donc vous aurez une erreur.
Vérifier les appels d’outils
Pour tester sans risque, créez un petit dossier :
mkdir -p /tmp/claude-mlx-test
cd /tmp/claude-mlx-test
printf 'print(6 * 7)\n' > test.py
claude
Demandez ensuite à Claude Code :
Lis le fichier test.py puis exécute-le.
S’il lit le fichier et affiche 42, les appels d’outils fonctionnent.
Les erreurs les plus courantes
En bonus, je vous mets une liste des erreurs les plus courantes :
Connection refused sur le port 8080 signifie que MLX n’est pas lancé ou utilise un autre port.
Une erreur 404 sur /v1/responses signifie que la variable LITELLM_USE_CHAT_COMPLETIONS_URL_FOR_ANTHROPIC_MESSAGES manque dans le terminal de LiteLLM.
Une erreur mentionnant claude-opus-4-8 signifie que ANTHROPIC_MODEL=claude-qwen-local n’est pas défini dans le terminal de Claude Code.
Une erreur 401 signifie généralement que ANTHROPIC_AUTH_TOKEN ne correspond pas au master_key de LiteLLM.
Enfin, le premier prompt peut prendre plusieurs minutes donc surveillez le terminal MLX pour voir si ça bosse ou pas.
Combien de mémoire faut-il vraiment ?
Comme je vous l'avais dit, le fichier du modèle fait 12,1 Go, mais ce n'est pas la consommation totale. Après mes essais, macOS comptait 18 Go d'empreinte pour MLX, avec un pic à 35 Go ainsi que 10,4 Go de cache de prompts. Un Mac 16 Go n'est donc pas suffisant. Pour ce 27B, même 32 Go de mémoire, ça reste un peu serré sur les gros contextes. Donc avec 16 Go, partez plutôt sur un modèle 7B ou 8B quantifié.
Enfin, le trafic du modèle et le code passent bien par 127.0.0.1 mais les téléchargements, vérifications de version et outils web restent du trafic réseau qui part vers le web. Donc si vous voulez un fonctionnement strictement hors ligne, préchargez le modèle, gardez CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 et désactivez les outils Web.
Le chemin qu'on a mis en place dans ce tuto pour OpenCode est propre et utilisable par contre le pont avec Claude Code fonctionne c'est vrai, mais Anthropic ne prend pas en charge les modèles non-Claude, non c'est possible qu'un jour, ça casse. Donc continuez à voir cette partie avec Claude comme un bricolage très utile mais absolument pas comme une API gravée dans le marbre.
Amusez-vous bien !