Brancher OpenClaw sur un LLM interne (souvent Ollama sur poste ou petit serveur, ou vLLM derrière un service OpenAI-compatible) évite d'expédier prompts hors périmètre, mais introduit une double surface réseau : la passerelle OpenClaw d'un côté, le producteur de tokens de l'autre. Ce runbook impose une cartographie explicite des URL, des délais alignés et une découpe de concurrence testée avant mise en charge. Pour verrouiller jeton, loopback et preuves doctor/status sur la passerelle elle-même, croisez avec
OpenClaw Gateway : liaison loopback, authentification par jeton et sondes doctor/status
; pour l'alignement disque, TCC et nœud local Apple Silicon avant d'ajouter des backends lourds, voyez
OpenClaw sur macOS local (Apple Silicon) : disque, iCloud et passerelle doctor.
GET /v1/models et doctor partagent la même identité réseau et les mêmes secrets effectifs.1. Cartographier les points d'accès : passerelle, reverse proxy et fournisseur
Le chemin nominal est outil → passerelle (surface type OpenAI) → Ollama ou vLLM. Erreurs fréquentes : préfixe de chemin manquant derrière Nginx ou Traefik, TLS terminé trop tôt sans réécriture des en-têtes, ou double base URL quand un plugin réinjecte une ancienne valeur. Dessinez une ligne par couche avec ports, schémas et noms DNS internes ; toute divergence entre curl direct vers le fournisseur et la passerelle doit être traitée comme bug de routage avant d'accuser le modèle. Ajoutez une colonne « schéma d'authentification » : certains outils n'envoient pas le même préfixe Bearer que la CLI, et un reverse proxy peut retirer un en-tête personnalisé sans que le producteur LLM ne s'en aperçoive.
Conservez un jeu de captures minimal : requête réussie vers le fournisseur seul, requête réussie vers la passerelle seule, puis la même charge via l'outil métier. Cette triade évite les boucles où l'on modifie les modèles alors que seul le chemin HTTP est incohérent. Versionnez les fichiers de configuration dans le dépôt qui pilote votre déploiement ; la reproductibilité passe avant l'optimisation des prompts.
2. Ollama sur LAN : liaison, noms de modèles et isolation
Conservez l'écoute sur une interface non exposée publiquement (loopback ou VLAN applicatif) et référencez les modèles avec la étiquette exacte vue par ollama list. Les timeouts côté client doivent dépasser la somme latence réseau + premier token ; sinon vous obtiendrez des coupures SSE ressemblant à des erreurs d'auth. Documentez la version du serveur Ollama dans le ticket de validation pour reproduire à l'identique. Sur Wi-Fi partagé ou VPN instable, privilégiez un câble ou un chemin réseau dédié pour la passerelle : les micro-coupures suffisent à faire varier le time-to-first-token et fausser vos réglages.
Si plusieurs postes consomment le même binaire Ollama, centralisez la liste des modèles autorisés pour éviter qu'un agent ne référence une variante quantifiée absente du serveur. Les messages d'erreur côté passerelle sont souvent génériques ; croisez toujours avec les journaux du serveur Ollama pour distinguer saturation disque, manque de VRAM unifiée et simple refus HTTP.
3. vLLM compatible OpenAI : concurrence serveur et garde-fous HTTP
vLLM agrège files GPU, batching et files d'attente HTTP : une rafale de requêtes peut saturer le planificateur avant la passerelle. Réglez des plafonds explicites côté service (sessions par worker, limites de batch) et faites correspondre la concurrence aval à ce que la passerelle autorise en amont. Mesurez la latence P95 sur /v1/chat/completions non streamé avant d'activer le streaming ; cela isole la pression KV de la pression proxy. Lorsque plusieurs modèles cohabitent, fixez des budgets GPU par file afin qu'un modèle expérimental ne fasse pas disparaître la capacité réservée aux agents de production.
Les erreurs « timeout » côté passerelle peuvent masquer une file saturée côté vLLM : augmentez d'abord la visibilité (métriques de file, profondeur de batch) avant d'allonger aveuglément les délais. Gardez une instance de secours ou un modèle plus petit pour les sondes /v1/models afin de ne pas bloquer la validation quand la grosse file est pleine.
4. Délais : empiler read-timeout, keep-alive et durées de génération
Les délais se cumulent : client HTTP, reverse proxy, passerelle, client interne vers Ollama/vLLM. Fixez une grille écrite (par exemple 30 s handshake, 120 s génération courte, 600 s job long) et testez une charge qui pousse le time-to-first-token. Sur flux SSE, un proxy qui ferme trop tôt tronque la réponse alors que le GPU continue — corrélez avec les journaux des deux côtés avant de modifier les secrets. Les clients qui renégocient TLS agressivement peuvent réinitialiser des connexions longues : désactivez les tests superflus sur le chemin interne.
Pour les jobs batch, préférez des réponses non streamées avec reprise idempotente ; pour le chat interactif, alignez le read timeout du client sur la durée maximale acceptable côté produit, puis descendez progressivement jusqu'au premier échec reproductible. Notez la valeur dans le runbook : c'est une donnée d'exploitation, pas un réglage « par défaut du framework ».
5. Découper la concurrence : tranches, files et budgets tokens
Attribuez des tranches par équipe ou par type de job : agents interactifs basse latence, batchs nocturnes haute fenêtre, tâches d'audit lecture seule. Côté passerelle, exposez des limites cohérentes avec la capacité GPU/RAM réelle ; côté orchestrateur, séparez les compteurs pour éviter qu'un seul outil monopolise les workers. Archivez les métriques tokens/seconde et requêtes actives lors des incidents pour calibrer la prochaine tranche. Une file par environnement (laboratoire, préproduction, production) réduit le bruit lors des tests de charge.
Quand vous ajoutez un nouvel outil, commencez avec une fenêtre de concurrence de 1 jusqu'à ce que doctor, /v1/models et une charge représentative soient verts simultanément ; montez ensuite par paliers de 25 % en observant la latence et l'utilisation mémoire. Les paliers documentés facilitent le retour arrière en cas de régression après upgrade.
6. Grille d'acceptation doctor / status
Exigez une capture verte sur la même machine utilisateur que le démon : chemins de configuration, plugins, connectivité RPC, cohérence des ports d'écoute. Comparez à une sonde /v1/models immédiatement après ; si doctor signale un avertissement mineur mais le HTTP échoue, priorisez le HTTP comme signal utilisateur et rouvrez un défaut réseau. Rejouez la séquence après chaque upgrade binaire ou rotation de secret.
doctorvert, HTTP rouge : URL de base, chemin ou en-tête proxy.- HTTP vert, streaming instable : timeouts et buffering proxy, pas le modèle.
- Les deux verts, latence explosive : saturation vLLM ou disque journal sur le nœud producteur.
7. Cas terrain : Mac distant haute mémoire pour « déborder » les grands contextes
Quand un poste de développement local manque de RAM unifiée pour tenir KV et caches d'outils, déplacez le producteur de tokens sur un Mac distant haute mémoire joignable en VPN basse latence, tout en gardant la passerelle OpenClaw sur un hôte contrôlé. Le flux devient : agents et plugins sur la machine légère, gros modèles et fenêtres longues sur le Mac distant — vous réduisez les risques de swap et stabilisez les délais de premier token. Documentez bande passante, MTU et résolveurs DNS internes ; une résolution lente suffit à faire échouer des healthchecks intermittents.
Sur ce Mac « débordement », isolez les journaux et caches sur un volume rapide, surveillez la pression thermique lors des runs longs, et figez les versions de backends accélérateurs (Metal sur Apple Silicon, pilotes GPU sur Linux) pour éviter les surprises après mise à jour système. Répliquez la séquence doctor + /v1/models depuis la passerelle en passant par le VPN exact utilisé en production : un test loopback sur le Mac distant ne suffit pas si le chemin réel traverse un tunnel ou un split-DNS.
Pourquoi un Mac mini haute mémoire simplifie ce couplage LLM privé
La pile « passerelle + producteur local » profite d'une mémoire unifiée large, d'un NVMe rapide pour journaux et artefacts, et d'une pile réseau macOS prévisible pour VPN et SSH. Le Mac mini combine faible consommation au repos (souvent autour de quelques watts), silence, services launchd stables, Gatekeeper, SIP et FileVault — moins de surprises qu'un PC générique derrière la même URL interne. Pour héberger Ollama ou un worker vLLM résident tout en gardant vos agents sur une autre machine, la bande passante mémoire compte autant que le CPU ; un Mac mini M4 avec mémoire étendue reste un socle rentable pour isoler les gros contextes des postes de développement.
Si vous voulez reproduire ce runbook sur un nœud distant aligné Macstripe, ouvrez la page d'accueil Macstripe pour choisir région et profil RAM ; le Mac mini M4 reste le point d'entrée le plus simple avant d'industrialiser vos tranches de concurrence et vos sondes doctor. Pour déporter sereinement les grands contextes tout en gardant une empreinte énergétique modeste au repos, le Mac mini M4 avec mémoire étendue est un excellent candidat — cliquez pour en savoir plus et composez votre nœud.
