Gateway

Bonjour découverte

OpenClaw peut utiliser Bonjour (mDNS / DNS-SD) pour découvrir un Gateway actif (point de terminaison WebSocket). La navigation multicast local. est une commodité réservée au LAN. Le Plugin bonjour fourni possède l’annonce LAN. Il démarre automatiquement sur les hôtes macOS et est activable sur Linux, Windows et les déploiements de Gateway conteneurisés. Pour la découverte inter-réseaux, la même balise peut aussi être publiée via un domaine DNS-SD étendu configuré. La découverte reste sans garantie et ne remplace pas la connectivité basée sur SSH ou Tailnet.

Bonjour étendu (DNS-SD unicast) sur Tailscale

Si le nœud et le Gateway sont sur des réseaux différents, le multicast mDNS ne franchira pas la frontière. Vous pouvez conserver la même expérience de découverte en passant à DNS-SD unicast (« Bonjour étendu ») sur Tailscale.

Étapes générales :

Exécuter un serveur DNS sur l’hôte du Gateway (joignable via Tailnet).
Publier les enregistrements DNS-SD pour _openclaw-gw._tcp sous une zone dédiée (exemple : openclaw.internal.).
Configurer le DNS fractionné Tailscale afin que le domaine choisi soit résolu via ce serveur DNS pour les clients (y compris iOS).

OpenClaw prend en charge n’importe quel domaine de découverte ; openclaw.internal. n’est qu’un exemple. Les nœuds iOS/Android parcourent à la fois local. et votre domaine étendu configuré.

Configuration du Gateway (recommandée)

{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
}

Configuration unique du serveur DNS (hôte du Gateway)

openclaw dns setup --apply

Cela installe CoreDNS et le configure pour :

écouter sur le port 53 uniquement sur les interfaces Tailscale du Gateway
servir le domaine choisi (exemple : openclaw.internal.) depuis ~/.openclaw/dns/<domain>.db

Validez depuis une machine connectée au tailnet :

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @&lt;TAILNET_IPV4&gt; -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Paramètres DNS Tailscale

Dans la console d’administration Tailscale :

Ajoutez un serveur de noms pointant vers l’IP tailnet du Gateway (UDP/TCP 53).
Ajoutez un DNS fractionné afin que votre domaine de découverte utilise ce serveur de noms.

Une fois que les clients acceptent le DNS tailnet, les nœuds iOS et la découverte CLI peuvent parcourir _openclaw-gw._tcp dans votre domaine de découverte sans multicast.

Sécurité de l’écouteur Gateway (recommandée)

Le port WS du Gateway (18789 par défaut) se lie par défaut au loopback. Pour un accès LAN/tailnet, liez explicitement et gardez l’authentification activée.

Pour les configurations tailnet uniquement :

Définissez gateway.bind: "tailnet" dans ~/.openclaw/openclaw.json.
Redémarrez le Gateway (ou redémarrez l’app de barre de menus macOS).

Ce qui annonce

Seul le Gateway annonce _openclaw-gw._tcp. L’annonce multicast LAN est fournie par le Plugin bonjour inclus quand le Plugin est activé ; la publication DNS-SD étendue reste détenue par le Gateway.

Types de service

_openclaw-gw._tcp - balise de transport du Gateway (utilisée par les nœuds macOS/iOS/Android).

Clés TXT (indications non secrètes)

Le Gateway annonce de petites indications non secrètes pour faciliter les flux d’interface utilisateur :

role=gateway
displayName=<friendly name>
lanHost=<hostname>.local
gatewayPort=<port> (Gateway WS + HTTP)
gatewayTls=1 (uniquement lorsque TLS est activé)
gatewayTlsSha256=<sha256> (uniquement lorsque TLS est activé et que l’empreinte est disponible)
canvasPort=<port> (uniquement lorsque l’hôte canvas est activé ; actuellement identique à gatewayPort)
transport=gateway
tailnetDns=<magicdns> (mode mDNS complet uniquement, indication facultative lorsque Tailnet est disponible)
sshPort=<port> (mode mDNS complet uniquement ; le DNS-SD étendu peut l’omettre)
cliPath=<path> (mode mDNS complet uniquement ; le DNS-SD étendu l’écrit quand même comme indication d’installation distante)

Notes de sécurité :

Les enregistrements TXT Bonjour/mDNS sont non authentifiés. Les clients ne doivent pas traiter TXT comme une source de routage faisant autorité.
Les clients doivent router à l’aide du point de terminaison de service résolu (SRV + A/AAAA). Traitez lanHost, tailnetDns, gatewayPort et gatewayTlsSha256 uniquement comme des indications.
Le ciblage automatique SSH doit également utiliser l’hôte de service résolu, et non des indications TXT seules.
L’épinglage TLS ne doit jamais permettre à un gatewayTlsSha256 annoncé de remplacer une épingle précédemment stockée.
Les nœuds iOS/Android doivent traiter les connexions directes basées sur la découverte comme TLS uniquement et exiger une confirmation explicite de l’utilisateur avant de faire confiance à une empreinte vue pour la première fois.

Débogage sur macOS

Outils intégrés utiles :

Parcourir les instances :
```
dns-sd -B _openclaw-gw._tcp local.
```

Résoudre une instance (remplacez <instance>) :

dns-sd -L "<instance>" _openclaw-gw._tcp local.

Si la navigation fonctionne mais que la résolution échoue, vous rencontrez généralement une politique LAN ou un problème de résolveur mDNS.

Débogage dans les journaux du Gateway

Le Gateway écrit un fichier journal rotatif (affiché au démarrage sous la forme gateway log file: ...). Recherchez les lignes bonjour:, en particulier :

bonjour: advertise failed ...
bonjour: suppressing ciao cancellation ...
bonjour: ... name conflict resolved / hostname conflict resolved
bonjour: watchdog detected non-announced service ...
bonjour: disabling advertiser after ... failed restarts ...

Bonjour utilise le nom d’hôte système pour l’hôte .local annoncé lorsqu’il s’agit d’une étiquette DNS valide. Si le nom d’hôte système contient des espaces, des traits de soulignement ou un autre caractère invalide pour une étiquette DNS, OpenClaw bascule vers openclaw.local. Définissez OPENCLAW_MDNS_HOSTNAME=<name> avant de démarrer le Gateway lorsque vous avez besoin d’une étiquette d’hôte explicite.

Débogage sur le nœud iOS

Le nœud iOS utilise NWBrowser pour découvrir _openclaw-gw._tcp.

Pour capturer les journaux :

Settings → Gateway → Advanced → Discovery Debug Logs
Settings → Gateway → Advanced → Discovery Logs → reproduire → Copy

Le journal inclut les transitions d’état du navigateur et les changements d’ensemble de résultats.

Quand activer Bonjour

Bonjour démarre automatiquement pour le démarrage du Gateway avec une configuration vide sur les hôtes macOS, car l’app locale et les nœuds iOS/Android à proximité reposent souvent sur la découverte sur le même LAN.

Activez Bonjour explicitement lorsque la découverte automatique sur le même LAN est utile sur Linux, Windows ou un autre hôte non macOS :

openclaw plugins enable bonjour

Quand il est activé, Bonjour utilise discovery.mdns.mode pour décider de la quantité de métadonnées TXT à publier. Le mode par défaut est minimal ; utilisez full uniquement lorsque les clients locaux ont besoin des indications cliPath ou sshPort, et utilisez off pour supprimer le multicast LAN sans modifier l’activation du Plugin.

Quand désactiver Bonjour

Laissez Bonjour désactivé lorsque l’annonce multicast LAN est inutile, indisponible ou nuisible. Les cas courants sont les serveurs non macOS, le réseau bridge Docker, WSL ou une politique réseau qui bloque le multicast mDNS. Dans ces environnements, le Gateway reste joignable via son URL publiée, SSH, Tailnet ou le DNS-SD étendu, mais la découverte automatique LAN n’est pas fiable.

Préférez la dérogation d’environnement existante lorsque le problème est lié au déploiement :

OPENCLAW_DISABLE_BONJOUR=1

Cela désactive l’annonce multicast LAN sans modifier la configuration du Plugin. C’est sûr pour les images Docker, les fichiers de service, les scripts de lancement et le débogage ponctuel, car le paramètre disparaît lorsque l’environnement disparaît.

Utilisez la configuration du Plugin lorsque vous voulez intentionnellement désactiver le Plugin de découverte LAN fourni pour cette configuration OpenClaw :

openclaw plugins disable bonjour

Pièges Docker

Le Plugin Bonjour inclus désactive automatiquement l’annonce multicast LAN dans les conteneurs détectés lorsque OPENCLAW_DISABLE_BONJOUR n’est pas défini. Les réseaux bridge Docker ne transmettent généralement pas le multicast mDNS (224.0.0.251:5353) entre le conteneur et le LAN, donc l’annonce depuis le conteneur permet rarement à la découverte de fonctionner.

Pièges importants :

Bonjour démarre automatiquement sur les hôtes macOS et est opt-in ailleurs. Le laisser désactivé n’arrête pas le Gateway ; cela ignore seulement l’annonce multicast LAN.
Désactiver Bonjour ne modifie pas gateway.bind ; Docker utilise toujours par défaut OPENCLAW_GATEWAY_BIND=lan, afin que le port hôte publié puisse fonctionner.
Désactiver Bonjour ne désactive pas le DNS-SD étendu. Utilisez la découverte étendue ou Tailnet lorsque le Gateway et le nœud ne sont pas sur le même LAN.
Réutiliser le même OPENCLAW_CONFIG_DIR hors de Docker ne persiste pas la politique de désactivation automatique du conteneur.
Définissez OPENCLAW_DISABLE_BONJOUR=0 uniquement pour le réseau hôte, macvlan ou un autre réseau où le multicast mDNS est connu pour passer ; définissez-le sur 1 pour forcer la désactivation.

Dépannage de Bonjour désactivé

Si un nœud ne découvre plus automatiquement le Gateway après une configuration Docker :

Confirmez si le Gateway fonctionne en mode automatique, forcé activé ou forcé désactivé :
```
docker compose config | grep OPENCLAW_DISABLE_BONJOUR
```
Confirmez que le Gateway lui-même est joignable via le port publié :
```
curl -fsS http://127.0.0.1:18789/healthz
```
Utilisez une cible directe lorsque Bonjour est désactivé :
- Control UI ou outils locaux : http://127.0.0.1:18789
- Clients LAN : http://<gateway-host>:18789
- Clients inter-réseaux : Tailnet MagicDNS, IP Tailnet, tunnel SSH ou DNS-SD étendu
Si vous avez volontairement activé le Plugin Bonjour dans Docker et forcé l’annonce avec OPENCLAW_DISABLE_BONJOUR=0, testez le multicast depuis l’hôte :
```
dns-sd -B _openclaw-gw._tcp local.
```
Si la navigation est vide ou si les journaux du Gateway affichent des annulations répétées du watchdog ciao, restaurez OPENCLAW_DISABLE_BONJOUR=1 et utilisez une route directe ou Tailnet.

Modes de défaillance courants

Bonjour ne franchit pas les réseaux : utilisez Tailnet ou SSH.
Multicast bloqué : certains réseaux Wi-Fi désactivent mDNS.
Annonceur bloqué en sondage/annonce : les hôtes avec multicast bloqué, les bridges de conteneurs, WSL ou les changements d’interface peuvent laisser l’annonceur ciao dans un état non annoncé. OpenClaw réessaie quelques fois puis désactive Bonjour pour le processus Gateway actuel au lieu de redémarrer l’annonceur indéfiniment.
Réseau bridge Docker : Bonjour se désactive automatiquement dans les conteneurs détectés. Définissez OPENCLAW_DISABLE_BONJOUR=0 uniquement pour l’hôte, macvlan ou un autre réseau compatible mDNS.
Veille / changements d’interface : macOS peut temporairement perdre les résultats mDNS ; réessayez.
La navigation fonctionne mais la résolution échoue : gardez des noms de machines simples (évitez les émojis ou la ponctuation), puis redémarrez le Gateway. Le nom d’instance de service dérive du nom d’hôte ; des noms trop complexes peuvent donc perturber certains résolveurs.

Noms d’instance échappés (`\032`)

Bonjour/DNS-SD échappe souvent les octets dans les noms d’instance de service sous forme de séquences décimales \DDD (par exemple, les espaces deviennent \032).

C’est normal au niveau du protocole.
Les interfaces utilisateur doivent décoder pour l’affichage (iOS utilise BonjourEscapes.decode).

Activation / désactivation / configuration

Les hôtes macOS démarrent automatiquement par défaut le Plugin de découverte LAN fourni.
openclaw plugins enable bonjour active le Plugin de découverte LAN fourni sur les hôtes où il n’est pas activé par défaut.
openclaw plugins disable bonjour désactive l’annonce multicast LAN en désactivant le Plugin fourni.
OPENCLAW_DISABLE_BONJOUR=1 désactive l’annonce multicast LAN sans modifier la configuration du Plugin ; les valeurs véridiques acceptées sont 1, true, yes et on (héritage : OPENCLAW_DISABLE_BONJOUR).
OPENCLAW_DISABLE_BONJOUR=0 force l’activation de l’annonce multicast LAN, y compris dans les conteneurs détectés ; les valeurs fausses acceptées sont 0, false, no et off.
Lorsque le Plugin Bonjour est activé et que OPENCLAW_DISABLE_BONJOUR n’est pas défini, Bonjour annonce sur les hôtes normaux et se désactive automatiquement dans les conteneurs détectés.
gateway.bind dans ~/.openclaw/openclaw.json contrôle le mode de liaison du Gateway.
OPENCLAW_SSH_PORT remplace le port SSH lorsque sshPort est annoncé (héritage : OPENCLAW_SSH_PORT).
OPENCLAW_TAILNET_DNS publie une indication MagicDNS dans TXT lorsque le mode mDNS complet est activé (héritage : OPENCLAW_TAILNET_DNS).
OPENCLAW_CLI_PATH remplace le chemin CLI annoncé (héritage : OPENCLAW_CLI_PATH).

Documentation associée

Politique de découverte et sélection du transport : Découverte
Appairage des nœuds + approbations : Appairage Gateway

# Bonjour étendu (DNS-SD unicast) sur Tailscale

# Configuration du Gateway (recommandée)

# Configuration unique du serveur DNS (hôte du Gateway)

# Paramètres DNS Tailscale

# Sécurité de l’écouteur Gateway (recommandée)

# Ce qui annonce

# Types de service

# Clés TXT (indications non secrètes)

# Débogage sur macOS

# Débogage dans les journaux du Gateway

# Débogage sur le nœud iOS

# Quand activer Bonjour

# Quand désactiver Bonjour

# Pièges Docker

# Dépannage de Bonjour désactivé

# Modes de défaillance courants

# Noms d’instance échappés (\032)

# Activation / désactivation / configuration

# Documentation associée