Installation OpenHuman échouée ? Guide complet de résolution d'erreurs 2026 (Mac / Windows / Docker / Node.js)

OpenHuman a rapidement attiré l'attention début 2026 avec son approche « local-first, mémoire à long terme » pour les agents IA personnels — mais le projet est encore en phase Early Beta. Ce guide recense de façon systématique les scénarios d'erreur les plus fréquents sur quatre plateformes, avec des commandes de correction directement exécutables.

Sommaire rapide

• Mac (Apple Silicon / Intel) : blocage Gatekeeper, chaîne d'outils Rust absente, conflit version Xcode CLT
• Windows : chemins avec espaces et caractères non-ASCII, kernel WSL2 trop ancien, mélange MSVC et GNU
• Docker : timeout de pull d'image, incompatibilité architecture arm64/amd64, erreurs de permissions volume
• Node.js : incompatibilité de version, échec de rebuild des modules natifs, conflits de dépendances pnpm/npm

1. Dépannage Mac (Apple Silicon & Intel)

1.1 Erreur : « openhuman » cannot be opened because the developer cannot be verified

macOS Gatekeeper bloque les binaires non notariés par Apple. Particulièrement fréquent sur les Mac Apple Silicon.

Solution A (recommandée — autoriser uniquement ce fichier) :

# Supprimez l'attribut de quarantaine une fois dans Terminal – l'app s'ouvre ensuite normalement
xattr -dr com.apple.quarantine /Applications/OpenHuman.app

Solution B (via Réglages système) : Ouvrir « Réglages système → Confidentialité et sécurité », trouver l'application bloquée en bas et cliquer sur « Ouvrir quand même ».

1.2 Erreur : error: linker `cc` not found

Le compilateur Rust ne trouve pas de linker C — généralement parce que les Xcode Command Line Tools ne sont pas installés ou sont trop anciens.

# Installer les Xcode CLT (~2 Go, réseau requis la première fois)
xcode-select --install

# Si déjà installé mais erreur persistante, réinitialiser le chemin
sudo xcode-select --reset

# Vérifier la version
xcode-select -p
# La sortie devrait être /Library/Developer/CommandLineTools ou /Applications/Xcode.app/...

1.3 Erreur : rustup: command not found ou version Rust trop ancienne

Le cœur Rust d'OpenHuman nécessite généralement stable ≥ 1.78.

# Installer rustup (ignorer si déjà installé)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Recharger l'environnement shell
source "$HOME/.cargo/env"

# Mettre à jour vers le dernier stable
rustup update stable

# Passer à la version requise par le dépôt (rust-toolchain.toml est appliqué automatiquement)
rustup show

1.4 Erreur : architecture arm64 is not compatible sur Apple Silicon

Certains modules natifs npm ou bibliothèques système ne fournissent pas de build arm64, ou les versions Rosetta et native de Homebrew sont installées simultanément.

# Confirmer l'architecture du shell actuel
uname -m  # doit afficher arm64 (shell natif puce M)

# Confirmer le chemin Homebrew (natif arm64 devrait être /opt/homebrew)
which brew

# Si brew pointe vers /usr/local (Rosetta), basculer vers le shell arm64 d'abord
arch -arm64 /bin/zsh
arch -arm64 brew install openssl pkg-config

1.5 Erreur : error: failed to run custom build command for `ring`

Le crate ring nécessite Clang/LLVM ; sur Mac, il faut spécifier explicitement le chemin OpenSSL.

# Installer OpenSSL 3 via Homebrew
brew install openssl@3

# Définir les variables d'environnement de build temporairement (ou ajouter à ~/.zshrc)
export OPENSSL_DIR="$(brew --prefix openssl@3)"
export OPENSSL_NO_VENDOR=1

# Relancer le build
cargo build --release

2. Dépannage Windows

2.1 Erreur : build échoue à cause d'espaces ou de caractères non-ASCII dans le chemin

Cargo et de nombreux modules natifs npm tolèrent très mal les espaces ou les caractères non-ASCII dans les chemins.

:: Cloner le dépôt dans un chemin ASCII pur sans espaces, par ex.
git clone https://github.com/tinyhumansai/openhuman C:\dev\openhuman

:: Migrer aussi le cache Cargo vers un chemin sûr (exécuter dans PowerShell)
[System.Environment]::SetEnvironmentVariable("CARGO_HOME","C:\dev\.cargo","User")
[System.Environment]::SetEnvironmentVariable("RUSTUP_HOME","C:\dev\.rustup","User")

2.2 Erreur : LINK : fatal error LNK1181

La chaîne d'outils MSVC est absente ou mal configurée. OpenHuman sur Windows recommande MSVC plutôt que GNU.

:: 1. Installer Visual Studio 2022 Build Tools (ou VS 2022 complet)
::    Composant obligatoire : « Développement Desktop en C++ » → MSVC v143 + Windows SDK

:: 2. Basculer Rust vers la cible MSVC
rustup default stable-x86_64-pc-windows-msvc
rustup target add x86_64-pc-windows-msvc

:: 3. Vérifier que l'éditeur de liens est accessible
where link
:: Exemple de sortie : C:\Program Files (x86)\Microsoft Visual Studio\...\link.exe

2.3 Erreur : kernel WSL2 trop ancien

Pour exécuter OpenHuman dans WSL2, le kernel doit être ≥ 5.15.

:: Mettre à jour le noyau WSL dans PowerShell (Administrateur)
wsl --update

:: Vérifier la version
wsl --version

:: Définir la distribution cible en mode WSL2
wsl --set-version Ubuntu-22.04 2

2.4 Erreur : 'python' is not recognized

Certains scripts de build de modules natifs npm dépendent de la commande python.

:: Option A : Installer python-is-python3 (WSL2 Ubuntu)
sudo apt install python-is-python3

:: Option B : Windows natif – pointer npm vers python3 globalement
npm config set python python3

:: Option C : Installer windows-build-tools (obsolète, préférer VS Build Tools)
:: Plus recommandé, à titre de référence seulement

2.5 Erreur : error MSB8036: The Windows SDK version X was not found

:: Ouvrir Visual Studio Installer → Modifier → Composants individuels
:: Cocher le Windows SDK correspondant (10.0.22621 ou plus récent recommandé) et installer
:: Redémarrer le terminal après l'installation avant de compiler

3. Dépannage Docker

3.1 Erreur : pull access denied ou timeout de pull

GitHub Container Registry et Docker Hub sont limités ou bloqués dans certaines régions.

# Option A : Configurer un miroir de registre (éditer dans Docker Desktop → Settings → Docker Engine)
# Ajouter le champ JSON suivant :
# "registry-mirrors": ["https://mirror.gcr.io","https://docker.mirrors.ustc.edu.cn"]

# Option B : Exporter l'image sur une machine avec accès réseau, puis la transférer
docker save ghcr.io/tinyhumansai/openhuman:latest | gzip > openhuman.tar.gz
# Importer sur la machine cible
gunzip -c openhuman.tar.gz | docker load

3.2 Erreur : incompatibilité de plateforme (linux/amd64 vs linux/arm64)

L'utilisation de l'image officielle amd64 sur un Mac Apple Silicon provoque cet avertissement.

# Télécharger en spécifiant explicitement la plateforme (déclenche l'émulation Rosetta, perte de perf)
docker pull --platform linux/amd64 ghcr.io/tinyhumansai/openhuman:latest

# Si une image arm64 officielle est disponible, préférer l'image native
docker pull --platform linux/arm64 ghcr.io/tinyhumansai/openhuman:latest

# Spécifier la plateforme à l'exécution
docker run --platform linux/arm64 ghcr.io/tinyhumansai/openhuman:latest

3.3 Erreur : permission denied — le conteneur ne peut pas écrire dans le volume

Le processus conteneur s'exécute en tant qu'utilisateur non-root, mais le répertoire hôte monté appartient à root.

# Option A : Accorder les permissions du répertoire hôte à l'utilisateur du conteneur (uid généralement 1000)
sudo chown -R 1000:1000 ./openhuman-data

# Option B : Exécuter en root dans docker run (développement uniquement, déconseillé en production)
docker run --user root ...

# Option C : Spécifier l'utilisateur dans Docker Compose
# services:
#   openhuman:
#     user: "1000:1000"
#     volumes:
#       - ./openhuman-data:/app/data

3.4 Erreur : exec: "sh": executable file not found

L'image utilise une base distroless ou scratch — aucun shell disponible.

# Entrer dans le conteneur avec le chemin bash complet (s'il existe)
docker exec -it openhuman /bin/bash

# Si l'image n'a vraiment pas de shell, construire une image de débogage et monter le volume de données original
docker build -f Dockerfile.debug -t openhuman-debug .
docker run -it --volumes-from openhuman openhuman-debug /bin/bash

3.5 Docker Compose : dependency failed to start

La base de données ou le service d'index vectoriel d'OpenHuman démarre lentement et le health check échoue.

# Ajouter un healthcheck pour les services dépendants dans compose.yml
# services:
#   db:
#     healthcheck:
#       test: ["CMD", "pg_isready", "-U", "openhuman"]
#       interval: 5s
#       retries: 10
#   openhuman:
#     depends_on:
#       db:
#         condition: service_healthy

# Inspecter manuellement les logs de chaque service pour identifier la cause racine
docker compose logs --tail=50 db
docker compose logs --tail=50 openhuman

4. Dépannage Node.js

4.1 Erreur : The engine "node" is incompatible with this module

Le frontend et la couche plugin d'OpenHuman nécessitent généralement Node.js ≥ 20 LTS.

# Basculer vers la version requise avec nvm (LTS 20 ou 22 recommandé)
nvm install 20
nvm use 20
node --version  # confirmer l'affichage de v20.x.x

# Si vous utilisez fnm (gestionnaire de versions plus rapide)
fnm install 20
fnm use 20

4.2 Erreur : gyp ERR! build error — échec du build de module natif

Des dépendances comme better-sqlite3 contiennent des add-ons natifs C++ et nécessitent une chaîne d'outils de build complète.

# macOS : s'assurer que les Xcode CLT sont installés
xcode-select --install

# Windows : installer node-gyp globalement dans PowerShell (Administrateur)
npm install -g node-gyp
# S'assurer également que Visual Studio Build Tools est installé (voir section 2.2)

# Linux (Ubuntu/Debian)
sudo apt-get install -y python3 make g++

# Forcer la reconstruction de tous les modules natifs
npm rebuild
# Ou avec pnpm
pnpm rebuild

4.3 Erreur : Cannot find module ERR_MODULE_NOT_FOUND

Installation de dépendances incomplète ou cache node_modules désynchronisé avec le lockfile.

# Nettoyage complet puis réinstallation
rm -rf node_modules
rm package-lock.json   # ou pnpm-lock.yaml / yarn.lock

# Réinstaller avec le gestionnaire de paquets du projet (exemple pnpm)
corepack enable
pnpm install --frozen-lockfile

4.4 Erreur : ENOSPC: System limit for number of file watchers reached

La limite de watchers inotify par défaut sous Linux est trop basse.

# Augmenter temporairement (remis à zéro après redémarrage)
sudo sysctl fs.inotify.max_user_watches=524288

# Rendre le paramètre permanent
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

4.5 Erreur : EACCES: permission denied, mkdir '.../.npm'

Problème de permissions sur le répertoire global npm.

# Changer le répertoire global npm vers un chemin accessible en écriture
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# Ajouter l'export ci-dessus à ~/.zshrc ou ~/.bashrc pour le rendre permanent

5. Checklist de dépannage général

Quelle que soit la plateforme, en cas de blocage, parcourez cette liste dans l'ordre :

#	Vérification	Commande rapide
①	Accès réseau à GitHub / crates.io / registry.npmjs.org	curl -I https://github.com
②	Version Git ≥ 2.40	git --version
③	Chaîne d'outils Rust stable conforme aux exigences	rustup show
④	Node.js ≥ 20 LTS	node --version
⑤	Espace disque libre ≥ 8 Go	df -h .
⑥	Vérifier les versions dans rust-toolchain.toml et .nvmrc	cat rust-toolchain.toml && cat .nvmrc
⑦	Capturer l'intégralité du journal d'erreurs	cargo build 2>&1 | tee build.log

6. Toujours bloqué ? Prochaines étapes

• Chercher dans le tracker d'issues : Rechercher les mots-clés de l'erreur dans GitHub Issues.
• Soumettre une issue détaillée : Coller la sortie de cargo build 2>&1 | head -100 avec rustup show, node --version et la version de votre OS.
• Utiliser Docker en repli : Si l'installation native continue d'échouer, un conteneur Docker est le moyen le plus rapide de contourner les différences d'environnement.
• Externaliser le backend d'inférence : Si les ressources locales sont insuffisantes, pointez l'endpoint modèle d'OpenHuman vers une instance Ollama distante.

Pour le pattern « ne peut pas installer localement → utiliser un nœud Mac distant », consultez notre article Base de connaissances OpenHuman en 20 min.

7. Conclusion

90 % des problèmes d'installation OpenHuman se ramènent à trois causes racines : chaîne d'outils de build incomplète, incompatibilité de version runtime et restrictions de permissions ou réseau. En suivant ce guide section par section, vous devriez résoudre la majorité des problèmes en moins de 30 minutes.

Si vous souhaitez simplement tester OpenHuman sans vous battre avec la configuration d'environnement, Docker est le point de départ le plus rapide. Pour un maximum de performance et un contrôle local total, investissez dans la configuration de la Rust toolchain et choisissez une machine Apple Silicon avec suffisamment de mémoire unifiée.