Un agent qui rédige, qui cherche, qui range — mais qui reste incapable de toucher un téléphone. C’est la limite que le plugin phone-harness fait sauter : il ajoute à Hermes un outil, phone_exec, qui exécute un court script Python sur un vrai téléphone et renvoie ce que l’écran affiche. Ouvrir une application, saisir du texte, faire défiler, lire une liste, prendre une capture : tout passe par le même canal.
Ce tutoriel couvre l’installation complète : ADB sur Windows, macOS et Linux, la préparation du téléphone, la connexion filaire pour Android 10, la connexion WiFi pour Android 11 et plus, l’accès hors du réseau local, puis l’installation du plugin dans Hermes.
Contenu
- 1 Ce que fait réellement phone-harness
- 2 Qu’est ce que ADB?
- 3 Installer ADB sur l’ordinateur
- 4 Préparer le téléphone
- 5 Android 10 : par USB, puis sans fil
- 6 Android 11 et plus : en WiFi
- 7 Sortir du réseau local sans ouvrir de port
- 8 Installer le plugin dans Hermes
- 9 Premier essai
- 10 Les limites à connaître
- 11 Ce que ça change vraiment
Ce que fait réellement phone-harness
Le plugin n’embarque pas de pilote maison : il s’appuie sur ADB, l’outil officiel d’Android, et sur le paquet phone_harness qu’il installe dans l’environnement de Hermes. L’agent écrit un script, le plugin le transmet, le téléphone l’exécute, la sortie revient.
phone_exec(code='''
ensure_device()
open_app("Horloge")
wait_stable()
print([o["text"] for o in screen()][:10])
''')
Ce qui remonte n’est pas une capture d’écran abstraite mais le texte réel des éléments affichés. L’agent travaille donc sur des données, pas sur des images — et quand une capture est nécessaire, elle est enregistrée et rattachée au résultat.
Qu’est ce que ADB?
ADB signifie Android Debug Bridge, et son nom décrit exactement ce qu’il fait : un pont entre un ordinateur et un appareil Android. Ce pont repose sur trois composants qui fonctionnent ensemble. Le premier est un client — c’est la commande adb que vous tapez, qui n’a qu’une durée de vie, celle de son exécution. Le deuxième est un serveur, un démon lancé sur l’ordinateur dès le premier appel, qui écoute en local sur le port 5037 et reste actif tant qu’on ne l’arrête pas. Le troisième est adbd, un démon qui tourne en permanence sur le téléphone lui-même.
Le client ne parle jamais directement au téléphone. Il transmet sa commande au serveur local, qui se charge de trouver l’appareil et de router la demande. C’est ce qui explique qu’une même commande puisse viser plusieurs téléphones branchés en même temps : le serveur tient le registre des appareils disponibles. La liaison entre le serveur et adbd se fait soit par USB, soit par TCP/IP — c’est cette seconde option qui permet le débogage sans fil. Avant d’établir la connexion, ADB vérifie l’identité de l’ordinateur par une paire de clés RSA : au premier branchement, le téléphone affiche une empreinte et demande votre accord, puis conserve la clé publique. C’est pour cette raison qu’un appareil fraîchement branché apparaît en unauthorized tant que vous n’avez pas validé la fenêtre, et en offline lorsque le démon ne répond plus.
Ce que ce pont ouvre est considérable : adb shell donne un interpréteur de commandes sur le téléphone, sous l’utilisateur shell et non root, ce qui suffit déjà à lister les applications, lire des fichiers, en installer, capturer l’écran ou simuler une saisie. C’est exactement ce que le plugin phone-harness exploite : il n’invente pas de protocole, il s’appuie sur ce pont officiel, fourni par Google et utilisé par Android Studio. Et c’est aussi ce qui justifie la mise en garde de ce tutoriel — un serveur ADB joignable depuis Internet n’exige aucun mot de passe pour exécuter des commandes sur l’appareil.
Installer ADB sur l’ordinateur
ADB fait partie des SDK Platform-Tools publiés par Google. Les liens de téléchargement officiels sont stables : ils pointent toujours vers la version la plus récente.
Windows
Le plus rapide, si vous disposez de winget :
winget install --id Google.PlatformTools -e
Sinon, téléchargez platform-tools-latest-windows.zip depuis la page officielle des Platform-Tools, puis extrayez l’archive dans C:\platform-tools — à la racine du disque, sans espace dans le chemin. Vérifiez ensuite :
cd C:\platform-tools .\adb.exe version
Pour utiliser adb depuis n’importe quel dossier, ajoutez le répertoire au PATH utilisateur :
[Environment]::SetEnvironmentVariable("Path",
[Environment]::GetEnvironmentVariable("Path","User") + ";C:\platform-tools", "User")
macOS
brew install android-platform-tools adb version
Sans Homebrew, la même archive existe en version darwin. Extrayez-la dans ~/platform-tools et ajoutez cette ligne à ~/.zshrc :
export PATH="$HOME/platform-tools:$PATH"
À noter : sur Mac, un iPhone ne passe pas par ADB mais par iPhone Mirroring, qui exige les autorisations Accessibilité et Enregistrement d’écran.
Linux
sudo apt install android-tools-adb adb version
Fedora : sudo dnf install android-tools. Arch : sudo pacman -S android-tools. Sur Debian et Ubuntu, ajoutez votre utilisateur au groupe plugdev, sans quoi adb devices répondra no permissions :
sudo usermod -aG plugdev $USER
Préparer le téléphone
La manipulation est identique sur tous les Android. Ouvrez Paramètres → À propos du téléphone → Numéro de build et touchez sept fois : le système confirme que le mode développeur est activé. Les Options pour les développeurs apparaissent alors dans Paramètres → Système.
C’est là que tout se joue, et le réglage diffère selon la version d’Android.
Android 10 : par USB, puis sans fil
Activez Débogage USB, branchez le câble, choisissez le mode Transfert de fichiers si le téléphone le demande, puis acceptez la fenêtre « Autoriser le débogage USB ? » en cochant « Toujours autoriser pour cet ordinateur ».
adb devices # R58M12345AB device
Android 10 ne connaît pas le débogage sans fil avec code d’association : il faut passer par le réseau en une seule commande, câble encore branché.
adb tcpip 5555 # restarting in TCP mode port: 5555
Débranchez ensuite le câble et connectez-vous à l’adresse réseau du téléphone :
adb connect 192.168.1.42:5555 adb devices # 192.168.1.42:5555 device
Le port 5555 reste fixe, mais il ne survit pas à un redémarrage du téléphone : il faut rebrancher le câble et relancer adb tcpip 5555.
Android 11 et plus : en WiFi
Depuis Android 11, le débogage sans fil est natif — et il n’utilise jamais le port 5555. Activez Débogage sans fil, puis touchez « Associer l’appareil avec un code » : le téléphone affiche une adresse, un port d’association et un code à six chiffres.
adb pair 192.168.1.42:37421 # saisir le code à six chiffres
Revenez ensuite à l’écran principal du débogage sans fil : il affiche un autre port, celui de connexion, différent du port d’association.
adb connect 192.168.1.42:41037 adb devices
Deux erreurs classiques ici. Utiliser le port 5555 renvoie connection refused, puisque rien n’écoute sur ce port. Et confondre le port d’association avec le port de connexion donne le même résultat : les deux chiffres sont affichés à deux endroits différents de l’écran.
Sortir du réseau local sans ouvrir de port
ADB accepte n’importe quelle adresse joignable, y compris hors du domicile — à condition de passer par un tunnel. Tailscale fait très bien l’affaire : installez-le sur le téléphone et sur l’ordinateur, puis utilisez l’adresse du tailnet à la place de l’IP locale.
adb connect 100.87.208.118:5555
Ne publiez jamais le port 5555 sur Internet. ADB n’applique aucune authentification : quiconque atteint le port peut exécuter des commandes sur le téléphone. Derrière un tunnel WireGuard, le problème disparaît ; en redirection de port sur la box, il devient une porte ouverte.
Installer le plugin dans Hermes
Dans un terminal, sur la machine où tourne Hermes :
hermes plugins install ShawnPana/phone-harness/integrations/hermes
Répondez oui à l’activation, puis fermez et relancez l’application : les outils ne se chargent qu’au démarrage, et une nouvelle conversation est nécessaire pour qu’ils apparaissent.
Déclarez enfin la plateforme, pour qu’Hermes sache quel type d’appareil piloter. Sous Windows :
[Environment]::SetEnvironmentVariable("PHONE_HARNESS_PLATFORM","android","User")
Sous macOS ou Linux :
export PHONE_HARNESS_PLATFORM=android
Premier essai
Dans une nouvelle conversation, demandez la lecture de l’écran :
phone_exec(code=''' ensure_device() print(screen()[:5]) ''')
Hermes affiche le script et demande votre accord avant de l’exécuter. Ce n’est pas une formalité : le plugin fait tourner du Python écrit par le modèle sur votre ordinateur, avec vos droits. L’approbation peut être accordée une fois, pour la session, ou de façon permanente.
Les limites à connaître
- Aucun mot de passe, code PIN ou 2FA. Le plugin ne les saisit pas : il rend le téléphone à l’utilisateur pour ces étapes, et c’est volontaire.
- iPhone : Mac uniquement. Le pilotage passe par iPhone Mirroring, absent de Windows et de Linux.
- Le mode automatique est une heuristique. Il évite l’approbation pour les scripts qui ne touchent qu’au téléphone, mais il est contournable : à laisser désactivé par défaut.
- Un téléphone par session. Les appels concurrents attendent leur tour, et au-delà de deux minutes l’outil signale l’appareil comme occupé.
Ce que ça change vraiment
La valeur n’est pas de télécommander un téléphone pour le plaisir. Elle est de donner à un agent une surface de plus : lire un écran d’application qui n’expose pas d’API, déclencher une action dans un service mobile, vérifier qu’un parcours utilisateur fonctionne réellement. C’est la différence entre un agent qui parle du monde et un agent qui y agit.