Public : la Gateway tourne, mais les outils MCP n’apparaissent pas, les appels expirent ou les Skills disparaissent après redémarrage. Résultat : garder le bootstrap dans le guide d’installation et le runbook Docker production ; garder la persistance dans l’article volumes & permissions Skills. Ce runbook couvre déclarer → visibilité processus → enregistrement Gateway → triage modèle / outil / canal. Plan : six pièges, deux matrices, esquisse de config, encadré d’avertissement, six étapes, trois KPI, conclusion.
MCP est une session JSON-RPC entre la Gateway et un processus enfant ou un point de terminaison distant. Des entrées de config existent ≠ l’enfant démarre ; l’enfant démarre ≠ les schémas reviennent. Six lectures erronées fréquentes suivent.
PATH ni les clés API de ~/.zshrc.AGENTS.md / bootstrap : des instructions dupliquées entre MCP et Skills gonflent le contexte ; séparer les limites comme dans la checklist d’ajustement Skills.Exécuter openclaw doctor selon l’ordre du guide doctor post-installation ; cet article ajoute la chaîne de preuve d’enregistrement des outils, pas un autre tutoriel d’installation.
Tenir une « carte de repro minimale » par serveur MCP : une requête en lecture, un test négatif qui doit être refusé, trois jetons de journal attendus—l’astreinte compare les cartes pour repérer les régressions de config sans relire d’immenses prompts. Noter sur la carte egress autorisé et classification des données pour qu’aucun incident n’élargisse les jetons sans trace.
Les noms de champs varient selon la version OpenClaw ; ce tableau fige l’ordre des opérations.
| Symptôme | Collecter d’abord | Cause probable | Action auditable |
|---|---|---|---|
| Liste d’outils vide ou partielle | Journaux Gateway, codes de sortie enfant | Binaire manquant, cwd, permission denied | command/args/cwd absolus ; lancer l’enfant avec le même utilisateur que la Gateway |
| Premier appel lent, puis ok | Timing cold-start, journaux de fetch paquets | npx -y ou JIT runtime | Préchauffe ; épingler versions dans images ; assouplir timeout du premier appel |
| Timeouts réguliers | Enfant vivant, CPU, usage FD | Deadlock, IO bloquant | Échantillonner/tracer si autorisé ; A/B avec un outil lecture seule |
| « Outil non enregistré » | Journaux schéma, version protocole | Décalage d’implémentation | Aligner versions MCP ; épingler mineurs ; lire changelog amont |
Publier une matrice de capacités pour qu’un même flux ne soit pas décrit trois fois.
| Source | Idéal pour | Versioning | Risque |
|---|---|---|---|
| ClawHub / marketplace | Expérimentation rapide | Épingler commit ou plage semver ; diff hebdo | Dérive amont—tests de régression nécessaires |
SKILL.md dépôt / packs privés | Flux lourds en conformité | Livrer avec la ligne principale via PR | Charge de maintenance ; aligner sur le périmètre MCP |
| MCP (référence) | BD, tickets, API HTTP internes | Cadence de release indépendante | Jetons trop larges—maintenir des listes blanches |
# Esquisse structurelle seulement—clés réelles, imbrication et hot reload suivent la doc OpenClaw actuelle.
# Objectif : la Gateway lance un serveur MCP sur stdio en tant qu’utilisateur fixe.
#
# mcpServers:
# internal-readonly-lookup:
# command: /usr/local/bin/node
# args: ["/opt/mcp-servers/lookup/dist/index.js"]
# env:
# LOOKUP_API_TOKEN: "${LOOKUP_TOKEN_READONLY}"
#
# Skill ClawHub : extraire/cloner dans le répertoire skills d’équipe, puis rafraîchir
# l’index des skills ou exécuter la commande reload documentée pour votre version.
Avertissement : MCP connecte les assistants aux données de production. Le moindre privilège et des pistes d’audit l’emportent sur « faire marcher à tout prix ». Séparer serveurs lecture et écriture, séparer les jetons, joindre des extraits de liste blanche au ticket de changement.
PATH, cwd et bind mounts.memory_search ou des outils doc pour freiner la croissance du contexte.AGENTS.md—tout >1 exige une dérogation signée.Sur Mac distants ou hôtes cloud, l’espace disque et la rotation des journaux affectent les enfants MCP qui écrivent des fichiers temporaires sur de petits volumes système—les timeouts peuvent sembler aléatoires alors que la config modèle est inchangée. Examiner l’exploitation hôte en parallèle de la config outil.
Pour les fronts MCP HTTP/SSE, inclure timeouts idle du reverse proxy, gestion Upgrade et terminaison TLS : la Gateway peut journaliser une poignée de main réussie pendant que le proxy edge renvoie 499/504. Croiser le guide reverse proxy Nginx/Caddy avant de ne monter que les timeouts OpenClaw.
Note communautaire directionnelle (pas un benchmark) : trois serveurs MCP lourds plus une récupération large produit souvent du jitter de file à l’échelle de la minute—matrices de capacités et listes blanches battent des plugins illimités pour le SLA.
Sommeil, à-coups VPN et dérive des chemins rendent processus enfants et index de skills imprévisibles. Relier de vraies données métier exige disponibilité 24/7, chemins persistants et permissions auditables.
Les machines autogérées sans choix multi-régions ni conditions flexibles poussent vers des hôtes partagés où cold starts et IO journaux se disputent la bande passante. Placer la Gateway sur de l’Apple Silicon dédié avec disques et egress prévisibles—typique d’un cloud Mac professionnel—rend souvent les politiques MCP et Skills contractuellement applicables. MACCOME propose des Mac mini M4 / M4 Pro multi-régions avec locations flexibles comme base stable pour Gateway et fermes de build ; vérifier tarifs publics et SLA du centre d’aide avant commande.
Piloter les trois contrôles de ce runbook sur un Mac distant avant de promouvoir une image sur toute la flotte—éviter les boucles « ok en local, timeout en prod ». Si la Gateway est exposée sur Internet, livrer TLS, limites de débit et listes blanches IP dans le même changement, pas comme correctif ultérieur.
FAQ
Comment cela s’associe-t-il à l’onboarding des canaux ?
Les guides canaux couvrent OAuth Slack/Discord/Telegram ; cet article couvre la découverte d’outils. Si les messages atteignent la Gateway mais que les tools échouent, rassembler des preuves depuis le tableau 1 avant de rouvrir les cas « connecté mais silencieux ».
Que doit inclure un rollback ?
Retirer les entrées MCP, documenter l’ordre de redémarrage, exécuter une requête de vérification en lecture seule et confirmer sur tableaux de bord que les comptes d’outils reviennent à la baseline. Aligner la facturation avec les tarifs de location.
Les chemins conteneur et bare metal divergent—que faire ?
Maintenir une matrice de chemins absolus par runtime ; ne jamais laisser le modèle deviner les chemins dans le chat. Croiser le centre d’aide avec l’article volumes Docker.