Matrice d'espace de noms · choix de mode_réseau · WebSocket de proxy inverse · autoriséOrigins · runbook en six étapes
Opérateurs auto-hébergant OpenClaw sur un VPS avec Compose souvent frappé par un mirage :docker compose psest vert, les journaux de la passerelle défilent, maisla CLI openclaw sur l'hôte ou dans un conteneur side-car continue d'expirer ou renvoie 502. La cause profonde réside généralement danscomment les espaces de noms réseau se combinent avec les adresses de liaison, pas la clé API du modèle. Cet article indiquequi a quel problème, utilise unarbre de symptômes à trois niveauxpour séparer la santé des processus de la véritable accessibilité, comparepont, hôte et network_mode : servicedans une matrice, parcourt unrunbook reproductible en six étapessur les ports publiés, les liaisons de bouclage, les mises à niveau WebSocket du proxy inverse etallowedOrigins, et se termine parfaits techniques vérifiables et matrice de décision. Relisez leBase de référence de production Docker Compose, leliste de contrôle d'isolation multi-instance, et leListe de contrôle pour le renforcement de la passerelle; pour les nœuds stables et la sortie prévisible, utilisez lepage de commande.
Une compositionhealthchecksonde souvent le bouclage à l’intérieur du conteneur ou l’activité du processus. Ilne prouve pas automatiquementque la résolution DNS, iptables et les proxys de l'espace utilisateur coopèrent tous sur le chemin allant d'un conteneur CLI au nom du service Gateway. Les cinq modèles ci-dessous arrivent ensemble dans des tickets ; les séparer affine immédiatement votre journal des incidents.
Écoute sur 127.0.0.1 uniquement :lorsque la passerelle lie le bouclage, les services frères sur le même pont se voient refuser la connexion via le nom du service ; cela ressemble à des délais d'attente aléatoires même si rien n'a jamais quitté cet espace de noms réseau.
CLI sur l'hôte avec un nom d'hôte de conteneur :copieropenclaw-gateway:18789dans un profil de shell hôte désaligne instantanément la résolution et le routage.
Le proxy inverse transmet HTTP mais pas la mise à niveau :les navigateurs ou les CLI utilisant WSS voient 400 ou les suppressions silencieuses tandis que les journaux d'application indiquent toujours que la passerelle est prête.
Les origines autorisées dérivent des origines réelles :le mélange de domaines de production, d'alias internes et de noms de style MagicDNS rejette les poignées de main au niveau de la couche application tandis que les captures de paquets semblent correctes.
network_mode : courses de redémarrage du service :après le redémarrage des modifications d'ordre, les avals touchaient toujours les anciennes adresses IP des conteneurs ou les mappages de ports obsolètes, produisant un succès intermittent.
Imprimez la section suivante sous forme de document de révision : autorisez la modification d'une seule cellule de la matrice par changement d'architecture et attachez des sorties appariées pour curl à l'intérieur du même espace de noms par rapport à curl de l'espace de noms externe.
Ajoutez une dimension temporelle : lors des mises à jour progressives, Compose exécute brièvement les anciens et les nouveaux conteneurs ensemble. Si les caches DNS et les pools de clients divergent, vous voyez la première requête réussit, puis quelques minutes d'échecs. Avant d'augmenter les délais d'attente, actualisez la résolution sur l'initiateur et comparez la réutilisation de la connexion avec le point de terminaison actuel de docker inspect. Si vous enchaînez également des proxys d'espace utilisateur ou d'entreprise, consignez les cibles de tunnel CONNECT séparément des cibles en accès direct, afin qu'un 407 du proxy ne soit pas pris à tort pour un échec d'authentification applicatif.
Un autre échec facile estMTU et fragmentationsur des chemins inter-nuages ou inter-opérateurs, qui se traduisent par des délais d'attente sporadiques. Lorsque des charges utiles volumineuses échouent alors que de minuscules contrôles de santé restent verts, limitez les captures aux tailles de trame WebSocket et aux limites d'enregistrement TLS au lieu de réécrire d'abord les routes des applications.
Une fois ces signaux présents dans le ticket de changement, alignez les horodatages entreopenclaw logset les journaux d’accès Edge. La plupart des équipes peuvent transformer un réseau mystérieux enun seul champ de configurationdans un délai de trente minutes, ce qui correspond également à la profondeur du contexte qu'un package de reproduction minimal doit contenir lorsqu'il demande une aide extérieure.
Lorsque vous choisissez un modèle, notezqui initie la connexion, quel nom se résout en quelle adresse et quelles couches NAT se situent entre les deux. Sans cette table, l'équipe joue au ping-pong entre les changementsports, extra_hosts, et le proxy inverse en amont.
| Modèle | Modèle d'écoute typique | Autres services dans le même fichier de composition | Processus hôtes |
|---|---|---|---|
| Pont par défaut avec ports publiés | 0.0.0.0à l'intérieur du conteneur ou des publications explicites | Utiliser le nom du service Compose et le port interne | Utiliser127.0.0.1:publishedou une adresse IP de carte réseau hôte |
| Réseau hôte | Partage la pile hôte ; les liaisons sont visibles par l'hôte | Autres conteneurs qui restent hors du pontne peut pasconserver l'ancien chemin du nom de service | Vérifiez les collisions de ports et les chaînes de pare-feu INPUT aux côtés des conteneurs |
| mode_réseau : service : passerelle | Partage les réseaux Gateway ; la sémantique de bouclage s'aligne | Les side-cars peuvent appeler127.0.0.1:gateway-port | L'hôte a toujours besoin de ports publiés ou d'un proxy ; rien n'est hérité automatiquement |
La véritable accessibilité signifie répéter les mêmes paramètres de nom d'hôte, de port et TLS à l'intérieurl'espace de noms du réseau initiateuret obtenir des réponses cohérentes, pas une boucle ponctuelle provenant d'un ordinateur portable.
La séquence conserve en premier les observations les moins chères ; arrêter et enregistrer la sortie chaque fois qu'une étape échoue. Si les noms de champs diffèrent de ceux de votre installation, vérifiez lesliste de contrôle d'installation et de dépannage du médecin.
Étiquetez l'initiateur :notez si les commandes s'exécutent sur l'hôte, dans un side-car Gateway ou dans un conteneur CLI autonome ; capturerhostnameet un courtip routerésumé.
Sonde HTTP à l'intérieur des réseaux :à partir de l'espace de noms de l'initiateur, GET ou HEAD le nom d'hôte et le port cible, vérifiez les codes d'état et les préfixes de corps et excluez toute défaillance DNS pure.
Sonde WebSocket :exercez le chemin de mise à niveau que vous utilisez réellement, enregistrez les en-têtes de réponse Edge par rapport à l'application et alignez les horodatages avec les journaux.
Matrice d'écoute à l'intérieur de Gateway :si les auditeurs se lient127.0.0.1uniquement et qu'un accès interservices est requis, passez à0.0.0.0ou adoptez un réseau partagé et mettez à jour le runbook en conséquence.
Quadruple proxy inverse :confirmer les points en amont sur l'IP du conteneur par rapport au port publié, vérifierConnectionetUpgradetransfert et assurez-vous que les délais d'inactivité ne coupent pas les sessions de longue durée.
Liste de contrôle des origines :énumérer réelOriginchaînes ou équivalents pour les navigateurs, les CLI et les CI ; chaque ligne manquante est un bloqueur de version.
docker compose ps
docker compose exec cli sh -lc 'getent hosts openclaw-gateway; curl -fsS -o /dev/null -w "%{http_code}\n" http://openclaw-gateway:18789/health || true'
curl -fsS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:18789/health || true
docker compose logs --no-color --tail=200 openclaw-gateway
Note:remplacez les noms de service, les ports et les chemins d'intégrité par les valeurs de votre référentiel ; conserver le modèle consistant à exécuter la même URL à partir de deux espaces de noms.
Cette section répertoriefaits que vous pouvez nommer dans les fichiers de configuration, pas des vibrations concernant le mauvais comportement des CDN. Pour connaître les limites de mémoire et le langage de rotation des journaux, revenez à la pageComposer la ligne de base de production.
ports:les mappages créent des règles DNAT sur l'hôte ; une mauvaise compréhension de l'ordre entre les politiques de pare-feu locales et les chaînes Docker entraîne un succès de conteneur à conteneur tandis que le chemin de l'hôte échoue, ou l'inverse.Avertissement:ne modifiez pas simultanément les amonts du proxy inverse, les liaisons de passerelle et la configuration CLI sans une ligne de base enregistrée ; les changements triangulaires rendent la bissection impossible.
Écrivez un booléen indiquant si la CLI doit partager la sémantique de bouclage avec la passerelle avant de choisirnetwork_mode: service:ou hôte. Utilisez la matrice pour la révision de la conception, pas pour les slogans.
| Contrainte | Valeur par défaut plus sûre | Signal d'acceptation clé | Risque principal |
|---|---|---|---|
| CLI et passerelle dans un seul fichier de composition | pont plus explicite0.0.0.0lie | la résolution du nom de service correspond à curl du port interne | La documentation du pare-feu et des ports publiés s'écarte de la réalité |
| Doit partager la sémantique localhost | side-car avecnetwork_mode: service:gateway | Le redémarrage du side-car ne ressuscite pas les pools de connexions obsolètes | couples de commande de mise à niveau avec autorisations de montage de volume |
| Le proxy inverse d'un hôte mature existe déjà | bouclage publié uniquement plus terminaison TLS à la périphérie | la preuve de paquet ou de journal montre une mise à niveau cohérente de WS | allowedOriginsmanque les formes d'URL que la CLI utilise réellement |
S'appuyer sur des scripts de tunnel ad hoc ou des fichiers hôtes édités manuellement lie le temps moyen de récupération à la mémoire individuelle. Lorsque les certificats en amont ou le DNS interne changent, le tri régresse vers des réunions à tous.
Piège courant :voir 502 et faire tourner les clés du modèle en premier ; terminez les sondes HTTP et WebSocket de la section trois avant de toucher les informations d'identification.
L’ouverture temporaire de ports sans liste de contrôle prouve rarement une posture de refus par défaut et d’autorisation explicite pour les audits. Lorsqu'OpenClaw doit être livré avec une sortie fixe, des noms d'hôte et une politique TLS mutuelle,Les couches réseau VPS ad hoc manquent souvent d'enregistrements de modifications signifiables. Pour les équipes qui ont besoin de versions iOS, d'un transfert de bureau et d'agents persistants surmachines dédiées avec des régions et des niveaux de réseau prévisibles, et je veux moins de boucles pour deviner les réseaux hôtes par rapport aux réseaux de conteneurs,La location cloud VpsMesh Mac Mini est généralement la meilleure solution: les nœuds dédiés simplifient la façon dont vous décrivez les écouteurs et les ACL dans le même langage quele runbook du réseau privé de l'équipe; le prix vit sur lepage de tarificationet des conseils de connectivité sur lecentre d'aide.
Exécutez des sondes HTTP à l'intérieurles mêmes réseaux que la CLI, puis validez la mise à niveau de WebSocket, puis revisitez les noms d'hôte CLI pour détecter un bouclage accidentel d'hôte ou des alias obsolètes. Pour le durcissement, voir leliste de contrôle de durcissement en production.
Utilisez-le lorsque les assistants doivent partager la pile Gateway et la vue de bouclage ; documenter l'ordre de redémarrage du service partagé et vérifier les notes officielles de connectivité dans lecentre d'aide.
Délais d'expiration en amont, transfert d'en-tête de mise à niveau manquant ouallowedOriginsdes lacunes pour l'origine réelle du client ; alignez les journaux Edge et les journaux d’application avant de faire pivoter les clés ou de modéliser les itinéraires. Pour les plans et les besoins de sortie, consultez lepage de tarification.