Ce guide suppose OpenClaw installé sur un Mac distant (type mini) et des dépôts en lecture seule séparés des zones d’écriture scratch. Pour les politiques d’outils schema-first et les modèles de repli partagés, prolongez notre article JSON Schema, timeouts, disjoncteur et retries ; pour les sémantiques de fil et de checkpoint associées aux graphes longs, voir checkpoints LangGraph et quotas sandbox sur Mac. Hygiène des jetons, disposition de la passerelle et base openclaw doctor : Centre d’aide · Guide OpenClaw.
Pourquoi lier les outils LangGraph à la passerelle avec des jetons
Lorsqu’un nœud d’outil appelle HTTP ou le shell directement, chaque auteur réinvente la gestion des secrets. Centraliser les appels derrière la passerelle OpenClaw offre un point de contrôle unique sur la boucle locale, un lieu pour attacher JSON Schema, limites de débit et journaux d’audit, et une surface où le jeton émis par le tableau de bord peut rester minimal : typiquement invoke:tools plus read:health, sans droits d’administration généralisés. Les workers LangGraph doivent lire le chemin du jeton via OPENCLAW_TOKEN_FILE, pas depuis du YAML versionné, et le même fichier doit alimenter le superviseur de processus et la sonde de santé planifiée afin que les erreurs de permissions apparaissent tout de suite.
Tableau de bord : émettre un jeton à privilèges minimaux
Ouvrez le tableau de bord OpenClaw dans une session autorisée à gérer le profil Mac distant. Créez un jeton dont le nom encode l’usage — par ex. langgraph-tools-prod — et restreignez les scopes au plus petit ensemble permettant d’exécuter les skills enregistrés et de lire l’endpoint de santé. Définissez un rappel de rotation ; collez le secret une fois dans ~/.openclaw/tokens/langgraph-tools.token sur le Mac, en mode 0600, propriétaire du même utilisateur UNIX que LangGraph. Pour plusieurs environnements, dupliquez le schéma avec des fichiers et des ports passerelle distincts afin que le staging et la production ne partagent jamais les mêmes jetons.
Passerelle en boucle locale, port fixe, un propriétaire
Démarrez la passerelle liée à 127.0.0.1 et à un port documenté par l’équipe — beaucoup de configurations standardisent 18765. Passez --token-file vers le secret du tableau de bord, redirigez stdout et stderr vers ~/openclaw-scratch/logs/gateway.log, et maintenez le processus sous launchd avec KeepAlive. Atteignez le port depuis votre portable via un tunnel SSH inverse ou une interface réseau privée, pas une exposition publique. Après modification, figez la configuration avec openclaw doctor --json > ~/openclaw-scratch/probe/doctor-langgraph.json pour comparer avant et après mise à jour.
Nœuds d’outils LangGraph : en-têtes, corrélation et schémas
Dans chaque implémentation d’outil qui appelle la passerelle, configurez le client HTTP avec l’URL de base http://127.0.0.1:18765 (ou l’hôte tunnelé), ajoutez Authorization: Bearer <jeton> lu depuis le fichier, et propagez X-Correlation-Id à partir de thread_id, de l’identifiant de checkpoint ou d’un autre identifiant stable du graphe. Validez le JSON sortant avec les mêmes schémas que pour les skills OpenClaw afin que le modèle ne puisse pas fabriquer des charges excessives. Si plusieurs graphes coexistent sur un même Mac, préfixez les noms d’outils dans les manifestes pour éviter les collisions et journalisez quel graphe a invoqué quel skill.
Politique de retry unifiée à la frontière outil
Les retries ne doivent pas être réécrits dans chaque nœud. Encapsulez les appels passerelle dans un module partagé : repli exponentiel avec jitter, maxAttempts raisonnable, gestion explicite de 408, 429 et 5xx, et aucun retry aveugle sur 401 ou 403 — ils signalent souvent rotation, dérive de scopes ou mauvais utilisateur. Journalisez chaque tentative avec nom du graphe, nom de l’outil, compteur de tentative et latence. Lorsque la passerelle applique son propre disjoncteur, remontez l’état au graphe pour qu’il puisse bifurquer vers une dégradation au lieu de marteler la même forme d’appel.
# Fragment de politique (YAML conceptuel)
retry:
maxAttempts: 4
initialDelayMs: 250
multiplier: 2.0
maxDelayMs: 8000
jitterRatio: 0.25
retryOnHttpStatus: [408, 425, 429, 500, 502, 503, 504]
neverRetryOnHttpStatus: [401, 403, 404, 422]Sondes de santé et échecs d’authentification : fusionner les alertes
Planifiez une sonde légère toutes les trois à cinq minutes qui exécute curl -fsS http://127.0.0.1:18765/health avec le même jeton Bearer que vos outils. En parallèle, acheminez les journaux structurés de la passerelle vers un fichier ou un collecteur et faites correspondre les lignes contenant 401 ou invalid_token. Injectez les deux contrôles dans un seul canal d’alerte avec un titre du type « Passerelle OpenClaw unhealthy ou jeton refusé », car coupures de tunnel, plantages de processus et mauvaises rotations arrivent souvent ensemble et les séparer trop tôt multiplie les pages. Escaladez séparément seulement si les astreintes diffèrent ; gardez la preuve détaillée dans le corps de l’incident fusionné.
FAQ opérationnelle
Port déjà utilisé (EADDRINUSE). Un autre écouteur occupe le port — souvent une seconde passerelle, un pont IDE ou un serveur de dev oublié. Utilisez lsof -nP -iTCP:PORT -sTCP:LISTEN, arrêtez le doublon ou choisissez un nouveau port et mettez à jour ensemble les URL de base LangGraph, les tunnels et les sondes. Un port canonique par profil évite la dérive silencieuse entre la carte du tableau de bord et vos graphes.
L’authentification réussit en curl depuis un shell mais échoue dans LangGraph. Comparez les utilisateurs UNIX entre votre test shell et le worker, vérifiez le chemin du fichier jeton dans l’environnement du graphe, assurez-vous que les branches async attachent l’en-tête sur chaque chemin awaitable, et confirmez que le tableau de bord n’a pas tourné le jeton pendant que launchd pointe encore vers un ancien chemin. Un décalage d’horloge au-delà de quelques secondes peut aussi invalider des jetons à fenêtre étroite : synchronisez avec sntp si vous utilisez des fenêtres de validité courtes.
Les retries amplifient les pannes. Baissez maxAttempts lorsque l’aval est clairement hors service, et laissez les disjoncteurs s’ouvrir avant que LangGraph ne passe des minutes dans des appels d’outils imbriqués. Associez les retries à des clés d’idempotence sur les routes mutantes lorsque les fournisseurs les supportent.
En bref : émettre un jeton tableau de bord à portée minimale, exécuter une passerelle en boucle locale avec port fixe et fichier de jeton, câbler les nœuds d’outils LangGraph via un client HTTP unique avec Bearer et identifiants de corrélation, centraliser les retries sans retenter aveuglément les 401, fusionner les échecs /health et d’authentification dans un flux d’alerte unique — puis valider avec openclaw doctor et des exercices de révocation de jeton.
Pour déployer cette architecture sur du matériel que vous n’avez pas à expédier en valise, louez un nœud cloud Mac mini M4 et gardez passerelle, journaux et graphes au même endroit : commencez par la page d’achat (régions et offres, consultation possible sans connexion), comparez les paliers sur la page tarifs, lisez les runbooks dans le centre d’aide, et parcourez d’autres playbooks dans le blog technique. Quand vous serez prêt à provisionner, ouvrez la console depuis l’accueil et appliquez les mêmes politiques de jetons et de retries partout.