Browser Relay · tunnels SSH · ports Gateway · runbook d'acceptation en six étapes
Vous exécutez OpenClaw Gateway sur un VPS ou un Mac cloud, mais vous voulez Chrome local avec l'extension officielle Browser Relay pour l'automatisation web — pas un autre conteneur Chromium headless. Échecs typiques : l'extension affiche connecté alors que CDP signale no tab is connected, ou vous voyez des 401 et des décalages de sonde de port après un tunnel SSH. Ce playbook s'adresse aux équipes qui ont besoin d'une séparation auditable entre plan de contrôle distant et navigateur de bureau réel : une matrice de décision face à Docker headless, une table de symptômes pour la santé 18792 et les paramètres de tunnel, plus un runbook en six étapes. Associez-le à la checklist navigateur headless et au runbook réseau Compose.
Dans les défauts 2026, Gateway écoute souvent sur 127.0.0.1:18789 tandis que Browser Relay sur un portable de dev écoute sur 127.0.0.1:18792. Déplacer Gateway sur un VPS distant sépare plan de contrôle et navigateur en espaces de noms réseau différents : l'agent parle encore de localhost, mais le navigateur est sur votre notebook. Les retours communautaires (Gateway distant plus tunnels SSH) convergent sur une auth relay qui ne vérifie qu'une map runtime locale (401 via tunnels), des sondes EADDRINUSE sur le mauvais port, et extension ON sans onglet attaché. Traiter la réponse des canaux comme acceptation complète gaspille des heures à régler les timeouts modèle.
Extension verte égale succès bout en bout : ON signifie seulement que le processus relay écoute ; sans ouvrir et attacher un onglet sur le site cible, CDP signale toujours no tab.
Direction de tunnel inversée : quand le Gateway distant doit atteindre le 18792 local, utilisez le forwarding distant -R ; mapper le 18789 distant vers le portable avec -L seul ne répare pas le plan navigateur.
Dérive token et table de ports : token relay, map tunnel et options extension doivent former un seul ensemble ; en changer un sans les autres produit 401 ou ports vides.
Mélange avec Docker headless : les conteneurs exigent shm_size ; le Relay local exige tunnels et attach — voir la checklist headless.
Lier Gateway à 0.0.0.0 par commodité : élargit l'exposition du plan de contrôle ; conservez loopback plus tunnel ou réseau privé selon l'article réseau.
Encodez les cinq points comme impératifs tunnel et motifs interdits dans votre ticket de changement. La section suivante fournit une matrice de validation entre conteneurs headless et Relay local avant les étapes d'acceptation copier-coller.
Choisissez selon où tourne le navigateur, qui détient la session utilisateur et les limites de conformité — pas selon la préférence personnelle. Un seul runbook après le tableau ; ne réglez pas les deux piles dans une même fenêtre de changement.
| Modèle | Quand il convient | Coût et risque principal |
|---|---|---|
| Docker Chromium headless | Batchs VPS sans surveillance, sans SSO portable | Pics shm/mémoire ; empreinte peut différer d'un profil réel |
| Chrome local + Relay | Cookies/SSO portable, debug avec humain dans la boucle | Tunnels SSH et attach extension ; Gateway distant ne doit pas exposer le navigateur à Internet |
| Mac cloud 24/7 dédié + Relay | Capacité équipe partagée dans une région | Coût ops plus élevé mais SLA défendable et modèles de tunnel |
La stabilité Relay repose surtout sur qui possède le port 18792, quel localhost le tunnel mappe et si les jetons forment un seul ensemble ; le reste est secondaire.
La guidance officielle 2026 recommande toujours openclaw onboard --install-daemon plus openclaw gateway status et openclaw doctor pour le plan de contrôle. Les skills navigateur ajoutent santé relay et attach d'onglet comme gates de release équivalents à Gateway vert.
Cette séquence prolonge la checklist d'installation Gateway : prouver le plan de contrôle, puis le plan navigateur. Collez les sorties dans le ticket à chaque étape.
Accepter Gateway : sur le VPS exécutez openclaw gateway status ; confirmez bind loopback sur 18789 (ou port documenté) ; accessibilité uniquement via proxy ou SSH.
Démarrer Relay local : installez l'extension Chrome ; exécutez curl -sS http://127.0.0.1:18792/health sur le portable.
Attacher un onglet : ouvrez le site cible et attachez via l'extension ; sans attach, no tab is connected est attendu.
Créer le tunnel : depuis le portable, p. ex. ssh -N -R 18793:127.0.0.1:18792 user@vps et pointez l'URL relay Gateway vers 127.0.0.1:18793 sur le VPS.
Aligner les jetons : faites correspondre jeton relay/gateway Gateway avec extension ou injection env ; sur 401 via tunnels, vérifiez les en-têtes jeton gateway plutôt que des maps runtime locales seules.
Skill bout en bout : exécutez un skill navigateur minimal en suivant openclaw logs --follow ; en échec, utilisez la table de symptômes, un paramètre à la fois.
curl -sS http://127.0.0.1:18792/health openclaw gateway status ssh -N -R 18793:127.0.0.1:18792 user@your-vps.example curl -sS http://127.0.0.1:18793/health
Conseil : si vous passez à des navigateurs headless en conteneur, utilisez la checklist skill headless plutôt que d'empiler des tweaks shm sur ce runbook.
Indexez d'abord par symptôme. Changez une variable par expérience et archivez extraits curl et journaux.
| Symptôme | Vérifier d'abord | Cause typique et action |
|---|---|---|
| Extension ON, skill indique no tab connected | Onglet ouvert et attaché sur l'URL cible | Gate opérationnel ; documenter dans le runbook |
| curl mapped-port /health échoue après tunnel | ssh -R actif, listener distant | Tunnel mort ou port pris ; ss -lntp |
| Relay 401 / unauthorized | En-têtes jeton et configs | Tunnel distant sans jeton gateway ; aligner configs |
| EADDRINUSE mais navigateur indisponible | Port sonde vs port Relay réel | Unifier table des ports |
| Timeout CLI Gateway | Accessibilité 18789, SSH -L | Lire l'article réseau avant d'incriminer Relay |
Attention : ne faites pas tourner clés API, certificats reverse-proxy et ports tunnel en un seul changement ; les triples moves ne sont pas bisectables.
Le Relay local convient au debug interactif et à l'identité portable ; changez de topologie pour des exécutions 24/7 sans surveillance ou si vous ne pouvez pas maintenir des tunnels personnels sur notebook.
| Signal | Action suggérée | Notes |
|---|---|---|
| Plusieurs utilisateurs dépendent du tunnel d'un seul portable dev | Passer à Docker headless ou Mac cloud dédié | Supprime le bus factor |
| Tunnel tombe chaque semaine à la mise en veille | Nœud régional 24/7 plus ssh/systemd standardisés | Suivre uptime tunnel dans le SLO |
| Exigence navigateur sur Internet public | Ne pas ; utiliser headless ou bureau à distance conforme | Relay suppose confiance loopback |
VPS ad hoc plus SSH manuel reste flexible au début, mais OpenClaw en production exige capacité validable et changements ticketés que les tunnels personnels offrent rarement. Placer Gateway et charges navigateur sur une empreinte Mac cloud 24/7 prévisible avec runbooks fixes bat les edits de ports sans fin. Pour les équipes ayant besoin d'une capacité Mac dédiée et stable par région, la location cloud Mac Mini VpsMesh est généralement le meilleur choix pour co-localiser plan de contrôle avec Relay ou profils headless. Voir tarifs et centre d'aide.
Utilisez -L 18789:127.0.0.1:18789 pour ramener le plan de contrôle Gateway distant sur le portable pour le debug. Utilisez -R pour que le VPS atteigne le 18792 local, en correspondance avec l'URL relay Gateway. Plus sur les timeouts plan de contrôle dans l'article réseau Compose.
Ouvrez et attachez d'abord un onglet sur le site cible. Si l'attach échoue encore, vérifiez santé du tunnel et jetons via la séquence journaux de la checklist d'installation.
Non recommandé. Conservez loopback plus SSH ou réseau privé, ou passez aux skills Docker headless ou un nœud dédié.