Trois erreurs d'interprétation qui retardent chaque session subagent
Erreur A : « Le modèle ne répond pas, donc sessions_spawn a disparu. » Avec une auth fournisseur invalide, un quota épuisé ou un alias de modèle erroné, la passerelle peut ne jamais entamer la phase de négociation d'outils alors que les healthchecks restent verts. Commencez par openclaw models status et un scénario de chat minimal avant de réécrire massivement le JSON.
Erreur B : placer allowAgents sur agents.defaults ou un nœud générique alors que les subagents attendent des politiques propres. Symptôme typique : allowed: none dans les diagnostics malgré un fichier « lisible ». Déplacez la politique sur l'entrée subagents concernée, persiste, redémarrez le service passerelle et comparez l'empreinte du fichier déployé avec l'artefact d'édition.
Erreur C : choisir un modèle sans function calling fiable pour la production. L'interface n'affiche alors pas spawn alors que les permissions sont correctes. Introduisez un modèle témoin reconnu pour les tools, documentez le résultat et marquez les routes non supportées dans la matrice interne pour aligner achats et engineering.
La logique de couches reprend le guide passerelle : processus et port locaux, puis API fournisseur, puis canaux et proxy. Mélanger l'ordre fait perdre des heures sur des diffs JSON quand la cause réelle est une clé API expirée.
Intégrez ces trois pièges dans l'onboarding : avant tout ticket, cocher modèle, nœud de politique, trafic proxy. Cela réduit le délai avant première hypothèse utile en supprimant les expériences parallèles bruyantes.
Pour l'audit, consignez dans chaque incident quelle couche a été écartée en premier et avec quelle preuve. Sans cette trace, les post-mortems répètent les mêmes graphiques alors que le proxy avait déjà été validé dès la première heure.
Points de douleur : releases, proxys, durcissement et dérive d'installation
Migration de schéma : les lignes majeures d'OpenClaw déplacent des clés dans openclaw.json. Ne mettre à jour que l'image conteneur ignore parfois silencieusement d'anciens champs. Lisez les notes de version, produisez des diffs structurés et exécutez openclaw doctor sur staging avec le même fichier qu'en production, pas une variante simplifiée.
Terminaison TLS et WebSockets : derrière Nginx ou Caddy, la même passerelle semble stable puis intermittente si les en-têtes Upgrade, les timeouts ou le buffering divergent. Symptôme : échecs sporadiques de subsessions malgré des tests locaux réussis. Croisez curl -N loopback et hostname public avec des identifiants de requête partagés entre la périphérie et l'application.
Production trop restrictive : les listes SSRF, filtres sortants et secrets webhook peuvent bloquer des callbacks d'outils légitimes pendant que doctor reste vert car les sondes empruntent d'autres chemins. Maintenez des règles explicites pour les hôtes de callback, documentez-les à côté des objets pare-feu et faites tourner les secrets sans fenêtre de politique vide.
Mélange d'installations : CLI npm global, Compose et LaunchAgents sur un même Mac distant font diverger which openclaw et le binaire réellement exécuté. Unifiez le chemin selon le guide d'installation avant de déboguer les subagents ; sinon vous « corrigez » des fichiers jamais lus par le processus actif.
Journaux peu structurés : sans hash de config, nom de modèle, résultat d'énumération d'outils et code de refus, les post-mortems restent vagues. Définissez des champs obligatoires pour le support et les exports automatisés afin de révéler les motifs récurrents.
Multi-équipes sur une machine : planifiez des fenêtres pour modifier proxy, passerelle et tokens bot en coordination. Les éditions parallèles produisent souvent des JSON à moitié valides avec résidus de merge que le parseur saute sans bruit.
Game-day trimestriel : injectez un allowAgents erroné, une clé API expirée et un webhook limité ; mesurez le temps jusqu'à la vraie racine via le runbook. Ajustez les tableaux de bord en conséquence plutôt qu'intuitivement.
À long terme, diagrammez le routage des outils : quels canaux héritent de quelles politiques subagent et où les exceptions PDF/Teams du guide multicanal s'appliquent. Sans carte, les exceptions se dupliquent et aggravent les incidents futurs.
Placer allowAgents sous subagents
Les subagents représentent des branches déléguées avec des frontières d'outils propres. Des politiques comme allowAgents s'appliquent par entrée, pas comme simple défaut global, selon la version et le schéma publié. Vérifiez la référence de release, pas de vieux snippets.
Avec plusieurs subagents, évitez le copier-coller sans ajuster les noms ; une faute de frappe fait tomber le bloc du parseur. Ajoutez une validation de schéma en CI si possible et versionnez des exemples de configuration.
Après modification, un simple reload ne suffit pas toujours : documentez le redémarrage supporté (systemd, LaunchAgent, Compose). Sans redémarrage, la config semble « à moitié » appliquée et génère des heisenbugs sous charge.
Multi-tenant : fichiers séparés ou utilisateurs Unix isolés ; un openclaw.json partagé sur l'hôte augmente le risque de lire la politique du mauvais mandant. Les tests automatisés doivent simuler au moins deux mandants synthétiques en parallèle.
Données personnelles : les subagents peuvent traiter du contexte sensible. Documentez quels outils sont autorisés par subagent et comment les durées de conservation sont appliquées, comme pour vos règles SFTP si la même infra porte artefacts et bots.
Revue sécurité : les outils à haut risque doivent vivre sur des subagents avec des profils réseau plus stricts ; un allow-all sur l'agent principal annule plus tard les durcissements en périphérie.
Function calling, choix de modèle et visibilité des outils
Le function calling (outils dans les complétions) est la condition pour voir sessions_spawn dans la négociation. Des endpoints spécialisés sans API d'outils produisent volontairement des listes courtes ; ce n'est pas une erreur de configuration mais une limite produit.
Tenez une table interne : ID modèle, support tools, coût, région, repli en panne. Mettez-la à jour à chaque changement tarifaire ou API pour que FinOps et astreinte partagent les mêmes hypothèses.
Charges mixtes—vision PDF du guide multicanal plus spawns—exigent des pools séparés pour éviter que de lourds jobs retardent la négociation d'outils. Mesurez les files distinctement et définissez des règles de shedding.
Feature flags : ne basculez jamais le chat principal sans le chemin subagent ; des alias divergents donnent un spawn OK en local et KO sur un canal.
QA : un test auto court qui attend une liste d'outils connue détecte mieux les régressions fournisseur qu'un clic manuel trimestriel dans l'UI.
Triage en couches : status, models status, doctor, journaux
Démarrez avec openclaw status : processus vivant, port ouvert, version attendue. Puis openclaw models status : clé valide, endpoint joignable, modèle présent. Ensuite openclaw doctor en JSON pour traitement machine ; enfin openclaw logs avec alignement fuseau sur le proxy.
Documentez un critère pass/fail par étape dans le runbook pour les astreintes de nuit. Injectez les liens vers les articles d'installation et passerelle dans le modèle de ticket.
Si modèles et doctor sont verts mais le canal bloque, basculez volontairement vers la couche proxy : mêmes chemins, mêmes en-têtes, même chaîne TLS. Utilisez des IDs de corrélation écrits par l'edge et la passerelle, sinon les extraits de journaux restent incohérents.
Pour les incidents récurrents, ajoutez un arbre de décision visuel au wiki ; les ancres visuelles réduisent les expériences parallèles qui s'invalident mutuellement.
Surveillez la fragmentation mémoire sur les longues durées si de nombreuses subsessions naissent et meurent ; planifiez des redémarrages rolling en fenêtre de maintenance sans couper les parcours utilisateur.
Formez le support à demander d'abord l'alias modèle, le canal et le dernier bloc allowAgents modifié ; beaucoup de tickets se closent là sans traces profondes.
Reverse proxy : WebSockets, timeouts, tampon
Les points publics derrière un reverse proxy exigent des règles Upgrade explicites et des timeouts de lecture suffisants pour streaming et canaux. Des valeurs courtes coupent des sessions qui ressemblent à des erreurs d'outils.
Vérifiez si le buffering casse le streaming ; comparez avec et sans terminaison TLS. Le dual-stack IPv4/IPv6 peut subir des timeouts différents—documentez les deux chemins.
Liez la rotation des certificats au même comité de changement que les upgrades passerelle ; des chaînes intermédiaires expirées produisent des handshakes aléatoires touchant seulement certaines régions.
Multi-environnements : séparez strictement server_name ou hôtes ; le mélange staging/production est une source fréquente de listes d'outils apparemment aléatoires.
Les CDN ajoutent des règles de cache ; assurez-vous que les chemins chat dynamiques et tools sont explicitement non mis en cache.
Durcissement : webhooks, SSRF et moindre privilège
Le guide durcissement production insiste sur le contrôle sortant et l'intégrité webhook. Les callbacks d'outils vers des services internes doivent apparaître dans les mêmes listes blanches que les autres sorties ; sinon le pare-feu empêche des spawns valides.
Faites tourner les secrets avec chevauchement court de deux versions valides jusqu'à mise à jour complète des bords. Automatisez via un gestionnaire de secrets plutôt que des tickets en clair.
Les scopes Graph ou bot doivent rester minimaux ; des droits excessifs amplifient l'impact d'un token volé. Croisez la revue des scopes avec le guide multicanal Teams/Telegram.
Des journaux d'audit pour les changements admin sur allowAgents expliquent les régressions après hotfix urgent. Sans eux, on ne sait pas si un humain ou un script de déploiement a déplacé la politique.
Les tests d'intrusion doivent tenter d'escalader les routes subagent ; documentez les résultats pour justifier des restrictions futures face aux produits qui veulent « juste élargir » les outils.
Matrice de décision
Utilisez le tableau en revue d'architecture et archivez la ligne choisie à côté des règles pare-feu et du coffre à secrets.
| Symptôme | Couche probable | Première action | Approfondir |
|---|---|---|---|
Pas de sessions_spawn | Modèle/endpoint | models status ; modèle témoin | Matrice function calling |
allowed: none | Nœud JSON | Vérifier allowAgents sous subagents | Sauvegarde JSON install |
| Échec seulement sur Internet | Proxy/WebSocket | curl loopback vs domaine | Guide Nginx/Caddy |
| Callbacks en timeout | Sortant/SSRF | Étendre allow-lists, auditer | Article durcissement |
| Décalage de versions | CLI vs service | Aligner chemins | Guide installation |
Définissez des SLO sur le taux de spawn réussi, la latence médiane jusqu'à la première réponse outil et les erreurs webhook ; reliez-les aux budgets d'erreur au-delà de la simple disponibilité API.
Mettez la matrice à jour après chaque release majeure car schéma et politiques par défaut bougent. Archivez les anciennes versions datées pour les auditeurs.
Utilisez-la aussi en revue coûts : chaque famille d'outils autorisée peut ajouter charge GPU ou files ; estimez avant d'ouvrir de nouveaux workflows subagent.
Sept étapes (illustration)
Adapter à votre environnement ; jamais de secrets dans tickets ou chats.
# 1) Aligner versions (CLI == service)
openclaw status
# 2) Fournisseur & modèle
openclaw models status
# 3) Config & doctor
openclaw doctor --json
# 4) Vérifier allowAgents sous agents.list[].subagents
# 5) Redémarrer la passerelle (LaunchAgent/systemd/Compose)
# 6) Proxy : curl -N https://votre.domaine/health vs loopback
# 7) Journaux avec IDs de requête
openclaw logs --follow
Documentez les dépendances proxy et durcissement dans les mêmes dépôts que la config passerelle pour éviter que des « optimisations » coupent silencieusement les callbacks d'outils.
Observabilité, rollback et culture d'exploitation
Métriques : compteurs d'échecs d'enregistrement d'outils, latences de spawn, retries webhook et callbacks refusés. Alertes sur des hausses sur fenêtres 15 minutes, pas seulement sur des pics absolus.
Ordre de rollback : d'abord alias modèle vers la dernière combinaison stable, puis annuler le diff allowAgents, ensuite changements proxy, enfin secrets canaux. Cela limite le nombre de variables simultanées.
Ajoutez des checks synthétiques qui touchent un chemin de spawn bénin sans fuite de données prod ; conservez des empreintes de réponse attendues.
Gardez des runbooks dans la langue de l'astreinte ; des résumés traduits à côté du long texte technique réduisent le stress de nuit.
Liez les tableaux de bord au guide multicanal si la charge PDF/Teams partage les mêmes workers ; des goulots communs évitent que des équipes s'optimisent en conflit.
FAQ et Mac distant géré
Pourquoi sessions_spawn manque après upgrade ?
Souvent migration de schéma, allowAgents mal placé ou modèle sans tools ; notes de version, models status et hiérarchie JSON.
Que faire avec allowAgents allowed:none ?
Attacher la politique au bon nœud subagents, valider le fichier, redémarrer la passerelle, comparer les hash.
doctor vert mais spawn qui échoue ?
Webhooks canal, buffering proxy ou filtre durcissement ; croiser les IDs edge/passerelle.
Conclusion : la visibilité de sessions_spawn est le produit des capacités modèle, du placement allowAgents et d'une infra propre. Le tri en couches fait gagner des heures par rapport au bricolage JSON aléatoire.
Limite : l'auto-hébergement exige un alignement continu roadmaps fournisseur, certificats et références sécurité. Les Mac distants gérés regroupent passerelles stables et parcours Apple Silicon reproductibles.
SFTPMAC fournit de la capacité Mac distant pour processus OpenClaw longue durée, entrées d'artefacts isolées et déploiements répétables sans colocation maison.
Quand les workflows subagent tournent 7×24, l'hébergement géré amortit vite la maintenance hardware nocturne et les chasses aux configs.
La CI doit linter schémas JSON et snippets proxy avant déploiement sur hôtes gérés ; la doc reste alignée avec le réellement en ligne.
Envisagez SFTPMAC si vous cherchez des Mac distants pour passerelles OpenClaw avec politiques d'outils claires et entrées SFTP séparées.