Sans callback localhost · matrice SSH/VNC · runbook huit étapes · grille vingt minutes
OpenClaw v2026.5.20 élève la connexion par abonnement xAI (Grok) au rang de chemin OAuth device-code de première classe : le terminal affiche une URL d'autorisation et un code à usage unique, le CLI distant interroge le endpoint token côté serveur — sans écouter 127.0.0.1:56121 sur la machine Gateway, sans forward SSH inverse du callback. Pour les équipes qui louent un Mac cloud avec poste principal Windows ou Linux, c'est un gain net : les identifiants Grok restent sur le nœud Gateway, l'autorisation navigateur se fait sur votre machine locale. Si vous bloquez sur « OAuth Codex qui route mal », « clé API seule qui n'aligne pas SuperGrok », ou « login SSH réussi mais Gateway 401 » — ce guide propose une voie auditable : chemin xAI orthogonal à la récupération Doctor/Codex v2026.5.6, matrice SSH × VNC, runbook en huit étapes, quatre conclusions prêtes pour ticket et FAQ. Commencez par le parcours d'installation dix minutes si CLI et Gateway ne tournent pas encore ; pour le routage Grok après auth, voir le guide multi-modèles ; pour l'alignement utilisateur launchd, la checklist daemon.
Avant v2026.5.20, beaucoup de nœuds cloud n'accédaient à Grok qu'avec une clé API nue ou un OAuth à callback localhost — la première n'aligne pas toujours X Premium / SuperGrok, la seconde casse dès que le navigateur est sur le portable et le Gateway dans le datacenter. Le device-code corrige la topologie d'autorisation, mais six familles d'incidents reviennent encore dans les tickets d'exploitation sur Mac loué.
OAuth callback incompatible avec le distant : le flux classique exige un retour navigateur vers http://127.0.0.1:56121/callback (port variable selon version). En SSH pur sur Mac loué, le navigateur local Windows reçoit le redirect alors que le listener vit sur le Gateway — token écrit au mauvais endroit ou timeout.
Contexte utilisateur CLI ≠ Gateway : lancer models auth login en root ou sous un autre compte macOS écrit le token dans le HOME de A alors que launchd fait tourner Gateway sous B — symptôme typique : « CLI OK, Gateway 401 ».
Version antérieure à v2026.5.20 : --auth-choice xai-device-code et --device-code n'existent pas ou se comportent mal sur d'anciens builds ; mélanger CLI npm global et binaire LaunchAgent obsolète masque le problème.
Confusion avec OAuth Codex : la série 5.5 a fusionné à tort openai-codex/* vers openai/* ; un alias xAI mal copié produit des échecs de refresh intermittents — après upgrade, exécutez openclaw doctor et croisez l'article 5.6.
Fenêtre de polling device-code : le code expire ; couper la session SSH ou changer de pane tmux interrompt le polling. Privilégiez un SSH stable ou un terminal dans la session VNC et validez vite dans le navigateur local.
Id modèle ≠ alias provider : OAuth réussi ne garantit pas que openclaw.json pointe vers xai/grok-* ; un fallback vers provider non autorisé donne « connecté mais 404/401 en inférence » — à valider avec le routage multi-modèles.
Ces échecs ne viennent pas de la qualité du modèle Grok mais de topologie réseau, discipline utilisateur et configuration post-auth. Le device-code supprime le premier goulot ; les cinq autres demandent une exploitation rigoureuse sur Mac loué, surtout quand plusieurs opérateurs partagent le même nœud ou quand un comité de changement exige des preuves reproductibles.
En pratique, la majorité des escalades « Grok ne marche pas » combinent au moins deux causes : callback mal routé et utilisateur launchd différent, ou OAuth réussi et modèle par défaut toujours sur OpenAI. Documenter chaque couche séparément dans le ticket évite les allers-retours entre équipe réseau, équipe identité et équipe modèles.
Le device-code réduit fortement le besoin de bureau graphique pour Grok OAuth, mais n'abolit pas VNC pour toute l'exploitation OpenClaw sur Mac distant. Le tableau suivant mappe chaque action d'acceptation vers le canal recommandé.
| Action d'acceptation | SSH seul | Compatible device-code | VNC conseillé | Critère de passage |
|---|---|---|---|---|
| openclaw --version / doctor | Suffisant | — | Optionnel | CLI et Gateway ≥ v2026.5.20, pas de conflit espace de noms xAI |
| onboard --auth-choice xai-device-code | Suffisant | Oui | Optionnel | Daemon installé, chemin token = utilisateur launchd |
| models auth login --provider xai --device-code | Suffisant | Oui | Optionnel | URL+code affichés, models list montre xai autorisé |
| Autorisation xAI dans navigateur local | N/A (poste opérateur) | Oui | Non requis | Pas de callback localhost côté Gateway |
| gateway restart + test Grok | Suffisant | — | Contre-preuve | Logs provider=xai, première réponse sans 401 |
| Console 18789 / panneau Network | sonde curl | — | Conseillé | WebSocket OK, alias grok visible, pas d'erreur mixed content |
| launchd même utilisateur / trousseau | logs texte | — | Conseillé | Aligné avec checklist daemon |
| Chaîne fallback multi-modèles | édition CLI config | — | Console | Fallback ne bascule pas vers provider non autorisé |
Modèle mental device-code xAI : SSH pour autoriser et redémarrer, VNC pour console et contre-preuve utilisateur — pas « OAuth = bureau obligatoire ». Seul le callback localhost:56121 impose quasi VNC ou port-forward.
Sur nœud Linux sans GUI, le device-code fonctionne aussi en SSH ; les canaux hors Grok (MCP navigateur, IM QR, micro Talk) peuvent encore exiger session graphique. Sur Mac Apple Silicon loué, la combinaison SSH device-code + VNC console reste le standard d'astreinte le plus court.
Quand un opérateur hésite entre OAuth navigateur classique et device-code, la règle est simple : si votre navigateur n'est pas sur la machine qui exécute login, choisissez device-code. Si vous êtes déjà en VNC sur le Mac Gateway avec Safari local, --method oauth peut suffire — mais documentez le port callback dans le ticket.
Ce runbook suppose un Mac distant loué avec accès SSH et, pour la contre-preuve finale, VNC optionnel. Chaque étape produit un artefact archivable : version CLI, capture URL+code, sortie doctor, extrait log Gateway.
Gel et sauvegarde : exportez config et état OpenClaw ; notez openclaw --version, utilisateur LaunchAgent, liste providers. Environnement neuf : suivez le parcours dix minutes.
Version ≥ v2026.5.20 : mettez à jour OpenClaw et alignez CLI et daemon Gateway sur le même build ; versions mixtes expliquent la majorité des « sous-commande introuvable ».
Nœud neuf — onboard intégré : sous le même utilisateur macOS que Gateway, lancez openclaw onboard --install-daemon --auth-choice xai-device-code ; ouvrez l'URL xAI imprimée dans votre navigateur local, saisissez le code ; attendez la fin du polling distant.
Gateway existant — ajout xAI : openclaw models auth login --provider xai --device-code ; copiez URL+code localement — ne configurez pas de callback localhost ni ssh -R 56121:.
Contre-preuve doctor : openclaw doctor pour espace de noms xAI, chemin token, absence d'alias Codex/OpenAI en double ; si vous venez de 5.5, croisez l'article 5.6.
Configurer le modèle Grok : dans openclaw.json, pointez le modèle principal vers xAI Grok (xai/grok-* selon openclaw models list) ; définissez fallback via routage multi-modèles sans ligne non autorisée.
Redémarrer Gateway : openclaw gateway restart, surveillez les logs launchd ; un simple nouveau terminal SSH ne recharge pas le daemon.
Test fumée et archivage : message court depuis console ou canal appairé ; conservez dans le ticket une ligne log provider=xai, model=grok ; en cas de 401, vérifiez contexte utilisateur puis alias modèle.
openclaw --version openclaw doctor # Nœud neuf : daemon + première connexion device-code xAI openclaw onboard --install-daemon --auth-choice xai-device-code # Gateway existant : OAuth xAI seulement openclaw models auth login --provider xai --device-code openclaw models list openclaw doctor openclaw gateway restart # Test fumée (adapter l'id modèle selon models list) openclaw agent --message "Réponds OK avec Grok" --model xai/grok
Chronologie device-code : le CLI demande un device_code à xAI → le terminal affiche URL + code → vous autorisez dans n'importe quel navigateur → le CLI sur le Mac distant interroge le endpoint token jusqu'à succès ou timeout → le token est écrit dans le stockage OpenClaw. La machine Gateway n'ouvre jamais 127.0.0.1:56121 — contraste net avec l'ancien OAuth à callback loopback, d'où l'intérêt du device-code comme voie privilégiée sur Mac cloud loué.
Pour les équipes qui standardisent les runbooks, figez trois règles dans le ticket : (1) toujours le même utilisateur macOS que launchd ; (2) jamais de forward 56121 si device-code est disponible ; (3) restart Gateway obligatoire après écriture token, même si le CLI de test répond déjà — le daemon charge les credentials au démarrage, pas à chaud.
Si Grok répond mais les tâches restent muettes, branchez la branche « sans réponse » du site (heartbeat, thinking, journaux canal) avant de rouvrir un ticket OAuth — les mots-clés 401 provider et « réponse vide » ne se cherchent pas dans les mêmes lignes de log. Inversement, une 401 immédiate après login réussi pointe presque toujours vers utilisateur launchd ou modèle par défaut, pas vers xAI en amont.
| Point de contrôle | Preuve SSH | Preuve VNC (conseillée) | Critère de passage |
|---|---|---|---|
| Version et doctor | --version, sortie doctor | Optionnel : panneau About | ≥ v2026.5.20, pas d'alerte OAuth/xAI |
| Autorisation device-code | URL+code terminal, log polling OK | Capture terminal même utilisateur | Fichier token xai présent dans credentials |
| Chargement Gateway | logs après gateway restart | Console en ligne, menu modèles | Premier Grok post-restart sans 401 |
| Routage modèle | models list, diff config | Alias grok sélectionné en console | Requêtes sur xai/grok-* |
| Contexte utilisateur | whoami, liste launchctl | Utilisateur bureau = SSH | Conforme checklist launchd |
Sur Mac cloud loué, l'intérêt d'un nœud VNCMac est précisément de boucler en une session graphique : device-code en SSH, console Gateway, vérification launchd même utilisateur — et de ramener « OAuth passé mais Gateway aveugle » de plusieurs heures de débat à vingt minutes d'acceptation auditable. Les équipes Windows peuvent figer le template d'astreinte « SSH login device-code + VNC console + navigateur local xAI ».
Imprimez ou collez dans le ticket la sortie de echo $HOME et whoami en SSH et en VNC avant de comparer les profils auth — les hôtes multi-HOME amplifient les décalages utilisateur pendant l'acceptation OAuth.
CLI, Gateway et premier échange.
Lire →OAuth Codex, fetch et Gateway — distinct de xAI.
Lire →Chaîne principale, fallback et alias Grok.
Lire →Même utilisateur, stabilité Gateway sur Mac loué.
Lire →Le device-code affiche URL xAI + code dans le terminal ; le CLI interroge le token sur le Mac distant. L'autorisation navigateur se fait sur votre poste ; Gateway n'écoute pas 127.0.0.1:56121. Le callback loopback exige navigateur et listener sur la même machine — incompatible avec « Gateway cloud, navigateur portable ».
Oui pour l'autorisation device-code : lancez login en SSH, validez dans un navigateur local. Pour console Gateway, utilisateur launchd ou trousseau, ouvrez VNC sous le même compte que le daemon.
Mac loué neuf : openclaw onboard --install-daemon --auth-choice xai-device-code. Gateway déjà en place : openclaw models auth login --provider xai --device-code, puis openclaw gateway restart.
1) openclaw doctor ; 2) versions CLI/Gateway alignées + restart ; 3) utilisateur token = utilisateur launchd ; 4) id modèle xai/grok-* sans fallback non autorisé. Sinon, croisez article 5.6 pour pollution d'alias.
Oui : OpenClaw réutilise les métadonnées client OAuth partagées de xAI. Le libellé Grok Build sur la page de consentement n'implique pas une mauvaise application — notez-le dans le ticket pour éviter une fausse escalade.
OpenClaw v2026.5.20 replace la connexion Grok par abonnement hors du labyrinthe du callback localhost : onboard ou models auth login en SSH, autorisation dans votre navigateur, polling et écriture du token sur le Mac distant — sans combattre 127.0.0.1:56121. La stabilité repose encore sur CLI et Gateway même version et même utilisateur, doctor, routage Grok et test fumée post-restart ; VNC sert à aligner console et preuves launchd quand SSH seul laisse un doute. Mac personnel ou VPS maison : veille, contexte utilisateur partagé et filtres egress restent des sources d'incidents ; sur Apple Silicon loué, terminal device-code et console Gateway dans une session VNC compressent souvent « OAuth passé, Gateway 401 » en vingt minutes d'acceptation traçable.
Pour un nœud pensé pour ce schéma SSH device-code + contre-preuve VNC, passez par VNCMac : location Mac cloud pour choisir région et formule ; centre d'aide pour les bases SSH-VNC avant d'ouvrir le port 18789 à toute l'équipe.