openclaw node

Exécutez un hôte Node sans interface graphique qui se connecte au WebSocket du Gateway et expose system.run / system.which sur cette machine.

Sur macOS, l’application de la barre des menus intègre déjà cet environnement d’exécution d’hôte Node dans sa propre connexion Node et ajoute des fonctionnalités Mac natives. Utilisez openclaw node run sur un Mac uniquement lorsque vous souhaitez volontairement un Node sans interface graphique et sans l’application. L’exécution des deux crée deux identités Node pour la même machine.

Pourquoi utiliser un hôte Node ?

Utilisez un hôte Node lorsque vous souhaitez que les agents exécutent des commandes sur d’autres machines de votre réseau sans y installer une application compagnon macOS complète.

Cas d’utilisation courants :

• Exécuter des commandes sur des machines Linux/Windows distantes (serveurs de compilation, machines de laboratoire, NAS).
• Maintenir l’exécution dans un bac à sable sur le Gateway, tout en déléguant les exécutions approuvées à d’autres hôtes.
• Fournir une cible d’exécution légère et sans interface graphique pour les automatisations ou les Nodes de CI.

L’exécution reste protégée par des approbations d’exécution et des listes d’autorisation propres à chaque agent sur l’hôte Node, afin que vous puissiez maintenir un accès aux commandes limité et explicite.

openclaw node run peut publier des outils fournis par un Plugin ou MCP après sa connexion. Par défaut, le Gateway approuve les descripteurs provenant du Node appairé, tout en exigeant que la commande de chaque descripteur demeure dans la surface de commandes approuvée du Node. L’agent voit chaque descripteur accepté comme un outil de Plugin normal, mais l’exécution passe toujours par node.invoke ; la déconnexion du Node supprime donc l’outil des nouvelles exécutions d’agent. Les opérateurs du Gateway peuvent désactiver la publication avec gateway.nodes.pluginTools.enabled: false.

Pour les outils MCP déclaratifs, ajoutez la structure habituelle du serveur MCP sous nodeHost.mcp.servers dans openclaw.json sur la machine du Node, puis redémarrez l’hôte Node. Le Node déclare la famille de commandes mcp.tools.call.v1, soumise à approbation, et publie les outils répertoriés après la connexion ; toute modification ultérieure de la liste des serveurs ne nécessite pas de nouvel appairage. Consultez Serveurs MCP hébergés par un Node.

Proxy de navigateur (sans configuration)

Les hôtes Node annoncent automatiquement un proxy de navigateur si browser.enabled n’est pas désactivé sur le Node. Cela permet à l’agent d’utiliser l’automatisation du navigateur sur ce Node sans configuration supplémentaire.

Par défaut, le proxy expose la surface normale des profils de navigateur du Node. Si vous définissez nodeHost.browserProxy.allowProfiles, le proxy devient restrictif : le ciblage des profils absents de la liste d’autorisation est rejeté et les routes de création/suppression de profils persistants sont bloquées par le proxy.

Désactivez-le sur le Node si nécessaire :

{  nodeHost: {    browserProxy: {      enabled: false,    },  },}

Exécution (premier plan)

openclaw node run --host <gateway-host> --port 18789

Options :

• --host <host> : hôte WebSocket du Gateway (valeur par défaut : 127.0.0.1)
• --port <port> : port WebSocket du Gateway (valeur par défaut : 18789)
• --context-path <path> : chemin de contexte WebSocket du Gateway (par ex. /openclaw-gw). Ajouté à l’URL WebSocket.
• --tls : utiliser TLS pour la connexion au Gateway
• --no-tls : forcer une connexion au Gateway en texte clair, même lorsque la configuration locale du Gateway active TLS
• --tls-fingerprint <sha256> : empreinte attendue du certificat TLS (sha256)
• --node-id <id> : remplacer l’identifiant d’instance client hérité stocké dans node.json (ne réinitialise pas l’appairage)
• --display-name <name> : remplacer le nom d’affichage du Node

Authentification au Gateway pour l’hôte Node

openclaw node run et openclaw node install déterminent l’authentification au Gateway depuis la configuration ou l’environnement (les commandes Node n’ont pas d’options --token/--password) :

• OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD sont vérifiées en premier.
• Puis vient la solution de repli de la configuration locale : gateway.auth.token / gateway.auth.password.
• En mode local, l’hôte Node n’hérite volontairement pas de gateway.remote.token / gateway.remote.password.
• Si gateway.auth.token / gateway.auth.password est explicitement configuré via SecretRef sans être résolu, la résolution de l’authentification du Node échoue de manière fermée (aucune solution de repli distante ne masque l’échec).
• En mode gateway.mode=remote, les champs du client distant (gateway.remote.token / gateway.remote.password) sont également admissibles selon les règles de priorité distante.
• La résolution de l’authentification de l’hôte Node ne tient compte que des variables d’environnement OPENCLAW_GATEWAY_*.

Pour un Node se connectant à un Gateway ws:// en texte clair, les adresses de bouclage, les littéraux d’IP privées, les hôtes .local et les hôtes Tailnet *.ts.net sont acceptés. Pour les autres noms DNS privés de confiance, définissez OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 ; sans cette variable, le démarrage du Node échoue de manière fermée et vous invite à utiliser wss://, un tunnel SSH ou Tailscale. Il s’agit d’une activation volontaire dans l’environnement du processus, et non d’une clé de configuration openclaw.json. openclaw node install la conserve dans le service supervisé du Node lorsqu’elle est présente dans l’environnement de la commande d’installation.

Service (arrière-plan)

Installez un hôte Node sans interface graphique en tant que service utilisateur (launchd sur macOS, systemd sous Linux, Planificateur de tâches Windows sous Windows).

openclaw node install --host <gateway-host> --port 18789

Options :

• --host <host> : hôte WebSocket du Gateway (valeur par défaut : 127.0.0.1)
• --port <port> : port WebSocket du Gateway (valeur par défaut : 18789)
• --context-path <path> : chemin de contexte WebSocket du Gateway (par ex. /openclaw-gw). Ajouté à l’URL WebSocket.
• --tls : utiliser TLS pour la connexion au Gateway
• --tls-fingerprint <sha256> : empreinte attendue du certificat TLS (sha256)
• --node-id <id> : remplacer l’identifiant d’instance client hérité stocké dans node.json (ne réinitialise pas l’appairage)
• --display-name <name> : remplacer le nom d’affichage du Node
• --runtime <runtime> : environnement d’exécution du service (node ou bun)
• --force : réinstaller/remplacer si le service est déjà installé

Gérez le service :

openclaw node statusopenclaw node startopenclaw node stopopenclaw node restartopenclaw node uninstall

Utilisez openclaw node run pour un hôte Node au premier plan (sans service).

Les commandes du service acceptent --json pour produire une sortie lisible par une machine.

L’hôte Node retente la connexion après les redémarrages du Gateway et les fermetures réseau au sein du processus. Si le Gateway signale une interruption définitive de l’authentification par jeton, mot de passe ou amorçage, l’hôte Node journalise les détails de la fermeture et se termine avec un code différent de zéro afin que launchd/systemd/Planificateur de tâches puisse le redémarrer avec une configuration et des identifiants actualisés. Les interruptions nécessitant un appairage restent dans le flux au premier plan afin que la requête en attente puisse être approuvée.

Appairage

La première connexion crée une demande d’appairage d’appareil en attente (role: node) sur le Gateway.

Lorsque l’hôte du Gateway peut se connecter à l’hôte Node par SSH sans interaction (même utilisateur, clé d’hôte de confiance), la demande en attente est approuvée automatiquement : le Gateway exécute openclaw node identity --json sur l’hôte Node via SSH et approuve en cas de correspondance exacte de la clé d’appareil. Ce comportement est activé par défaut ; consultez Approbation automatique des appareils vérifiée par SSH pour connaître les exigences et la procédure de désactivation (gateway.nodes.pairing.sshVerify: false).

Sinon, approuvez-la manuellement avec :

openclaw devices listopenclaw devices approve <requestId>

Inspectez l’identité locale du Node par rapport à laquelle le Gateway effectue la vérification :

openclaw node identity --json

Cette commande affiche l’identifiant de l’appareil et la clé publique provenant de identity/device.json, sans jamais créer ni modifier de fichiers d’identité.

Sur les réseaux de Nodes strictement contrôlés, l’opérateur du Gateway peut explicitement choisir d’approuver automatiquement le premier appairage des Nodes provenant de CIDR de confiance :

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

Ce comportement est désactivé par défaut (autoApproveCidrs n’est pas défini). Il s’applique uniquement à un nouvel appairage role: node sans portée demandée, provenant d’une adresse IP cliente à laquelle le Gateway fait confiance. Les clients opérateur/navigateur, Control UI, WebChat, ainsi que les mises à niveau de rôle, de portée, de métadonnées ou de clé publique nécessitent toujours une approbation manuelle.

Si le Node retente l’appairage avec des informations d’authentification modifiées (rôle/portées/clé publique), la demande précédente en attente est remplacée et un nouveau requestId est créé. Exécutez de nouveau openclaw devices list avant l’approbation.

État de l’identité et de l’appairage

Le Node sans interface graphique sépare son identifiant d’instance client hérité de l’identité d’appareil signée que le Gateway utilise pour l’appairage et le routage. Ces fichiers se trouvent dans le répertoire d’état d’OpenClaw (~/.openclaw par défaut, ou $OPENCLAW_STATE_DIR lorsque cette variable est définie) :

--node-id modifie uniquement l’identifiant d’instance client dans node.json. Il ne modifie pas l’identifiant cryptographique de l’appareil et n’efface pas l’authentification d’appairage. La suppression du seul fichier node.json ne réinitialise pas non plus l’appairage. Pour révoquer et réappairer un Node :

1. Sur le Gateway, exécutez openclaw nodes remove --node <id|name|ip>.
2. Sur le Node, redémarrez le service installé avec openclaw node restart, ou arrêtez puis relancez la commande au premier plan openclaw node run. Cela démarre le flux d’appairage de l’appareil. Si openclaw devices list n’affiche aucune demande et que le Node signale AUTH_DEVICE_TOKEN_MISMATCH, redémarrez-le ou relancez-le encore une fois. La tentative rejetée efface le jeton local désormais révoqué ; la tentative suivante peut demander l’appairage.
3. Sur le Gateway, exécutez openclaw devices list, puis openclaw devices approve <deviceRequestId>.
4. Redémarrez ou relancez de nouveau le Node. Un client interrompu pour appairage ne reprend pas automatiquement après l’approbation ; cette reconnexion crée la demande distincte de surface de commandes.
5. Sur le Gateway, exécutez openclaw nodes pending, puis openclaw nodes approve <nodeRequestId>.

Les deux identifiants de demande sont distincts. Une politique applicable de CIDR de confiance peut approuver automatiquement l’étape du premier appairage de l’appareil ; l’approbation de la surface de commandes reste une vérification distincte.

Les anciennes versions d’OpenClaw pouvaient laisser un champ token hérité dans node.json. La version actuelle d’OpenClaw n’utilise pas ce champ et le supprime la prochaine fois que l’hôte Node enregistre le fichier. Conservez les deux fichiers sous identity/ privés ; ils contiennent la paire de clés de l’appareil et les jetons d’authentification.

Approbations d’exécution

system.run est soumis aux approbations d’exécution locales :

• $OPENCLAW_STATE_DIR/exec-approvals.json, ou ~/.openclaw/exec-approvals.json lorsque la variable n’est pas définie
• Approbations d’exécution
• openclaw approvals --node <id|name|ip> (modification depuis le Gateway)

Pour l’exécution asynchrone approuvée sur un Node, OpenClaw prépare un systemRunPlan canonique avant de demander l’approbation. Le transfert ultérieur de la commande approuvée system.run réutilise ce plan stocké ; les modifications des champs de commande/répertoire de travail/session après la création de la demande d’approbation sont donc rejetées au lieu de modifier ce que le Node exécute.

Voir aussi

• Référence de la CLI
• Nodes