Ошибка установки OpenHuman? Полное руководство по решению проблем 2026 (Mac / Windows / Docker / Node.js)

OpenHuman быстро привлёк внимание в начале 2026 года благодаря концепции «local-first, долгосрочная память» для персональных ИИ-агентов — но проект всё ещё находится в стадии Early Beta. Двойной стек сборки Rust + TypeScript, системные зависимости и различные модели прав доступа на разных платформах приводят к тому, что многие пользователи застревают на самом первом шаге. Это руководство систематически охватывает наиболее распространённые сценарии ошибок на четырёх платформах с командами исправления, готовыми к запуску.

Быстрый поиск

• Mac (Apple Silicon / Intel): блокировка Gatekeeper, отсутствие цепочки инструментов Rust, конфликт версий Xcode CLT
• Windows: пробелы в путях и не-ASCII символы, устаревшее ядро WSL2, смешение MSVC и GNU
• Docker: таймаут загрузки образа, несовместимость архитектур arm64/amd64, ошибки прав доступа тома
• Node.js: несовместимость версий, сбой пересборки нативных модулей, конфликты зависимостей pnpm/npm

1. Устранение неполадок на Mac (Apple Silicon и Intel)

1.1 Ошибка: «openhuman» cannot be opened because the developer cannot be verified

macOS Gatekeeper блокирует бинарные файлы, не прошедшие нотаризацию Apple. Особенно часто встречается на Mac с Apple Silicon.

Решение A (рекомендуется — разрешить только этот файл):

# Удалите атрибут карантина в Terminal один раз — после этого приложение откроется двойным кликом
xattr -dr com.apple.quarantine /Applications/OpenHuman.app

Решение B (через Системные настройки): Открыть «Системные настройки → Конфиденциальность и безопасность», найти заблокированное приложение внизу и нажать «Всё равно открыть».

1.2 Ошибка: error: linker `cc` not found

Компилятор Rust не может найти компоновщик C — обычно это означает, что Xcode Command Line Tools не установлены или устарели.

# Установить Xcode CLT (~2 ГБ, при первой установке нужна сеть)
xcode-select --install

# Если уже установлено, но ошибка не уходит, сбросить путь
sudo xcode-select --reset

# Проверить версию
xcode-select -p
# Вывод должен быть /Library/Developer/CommandLineTools или /Applications/Xcode.app/...

1.3 Ошибка: rustup: command not found или устаревшая версия Rust

Ядро Rust OpenHuman обычно требует stable ≥ 1.78.

# Установить rustup (пропустить, если уже установлен)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Перезагрузить окружение shell
source "$HOME/.cargo/env"

# Обновить до последнего stable
rustup update stable

# Переключиться на версию, требуемую репозиторием (rust-toolchain.toml применяется автоматически)
rustup show

1.4 Ошибка: architecture arm64 is not compatible на Apple Silicon

Некоторые нативные npm-зависимости или системные библиотеки не предоставляют сборку arm64, или одновременно установлены версии Homebrew для Rosetta и нативная.

# Проверить архитектуру текущего shell
uname -m  # должно вывести arm64 (нативный shell чипа M)

# Проверить путь Homebrew (нативный arm64 должен быть /opt/homebrew)
which brew

# Если brew указывает на /usr/local (Rosetta), сначала переключиться на arm64 shell
arch -arm64 /bin/zsh
arch -arm64 brew install openssl pkg-config

1.5 Ошибка: error: failed to run custom build command for `ring`

Крейт ring требует Clang/LLVM; на Mac необходимо явно указать путь к OpenSSL.

# Установить OpenSSL 3 через Homebrew
brew install openssl@3

# Временно задать переменные окружения сборки (или добавить в ~/.zshrc)
export OPENSSL_DIR="$(brew --prefix openssl@3)"
export OPENSSL_NO_VENDOR=1

# Повторить сборку
cargo build --release

2. Устранение неполадок на Windows

2.1 Ошибка: сборка завершается с ошибкой из-за пробелов или не-ASCII символов в пути

Cargo и многие нативные npm-модули плохо переносят пробелы или не-ASCII символы в путях.

:: Клонировать репозиторий в путь из ASCII-символов без пробелов, например
git clone https://github.com/tinyhumansai/openhuman C:\dev\openhuman

:: Перенести кэш Cargo в безопасный путь (выполнить в PowerShell)
[System.Environment]::SetEnvironmentVariable("CARGO_HOME","C:\dev\.cargo","User")
[System.Environment]::SetEnvironmentVariable("RUSTUP_HOME","C:\dev\.rustup","User")

2.2 Ошибка: LINK : fatal error LNK1181

Цепочка инструментов MSVC отсутствует или неправильно настроена. На Windows рекомендуется MSVC, а не GNU.

:: 1. Установить Visual Studio 2022 Build Tools (или полный VS 2022)
::    Обязательный компонент: «Разработка классических приложений на C++» → MSVC v143 + Windows SDK

:: 2. Переключить Rust на MSVC target
rustup default stable-x86_64-pc-windows-msvc
rustup target add x86_64-pc-windows-msvc

:: 3. Убедиться, что компоновщик доступен
where link
:: Пример вывода: C:\Program Files (x86)\Microsoft Visual Studio\...\link.exe

2.3 Ошибка: ядро WSL2 слишком старое

При запуске OpenHuman в WSL2 ядро должно быть ≥ 5.15.

:: Обновить ядро WSL в PowerShell (от имени администратора)
wsl --update

:: Проверить версию
wsl --version

:: Перевести целевой дистрибутив в режим WSL2
wsl --set-version Ubuntu-22.04 2

2.4 Ошибка: 'python' is not recognized

Некоторые скрипты сборки нативных npm-модулей зависят от команды python.

:: Вариант A: установить python-is-python3 (WSL2 Ubuntu)
sudo apt install python-is-python3

:: Вариант B: Windows-нативный — указать python3 в глобальных настройках npm
npm config set python python3

:: Вариант C: установить windows-build-tools (устарел, рекомендуется VS Build Tools)
:: Больше не рекомендуется, только для справки

2.5 Ошибка: error MSB8036: The Windows SDK version X was not found

:: Открыть Visual Studio Installer → Изменить → Отдельные компоненты
:: Отметить нужный Windows SDK (рекомендуется 10.0.22621 или новее) и установить
:: После установки перезапустить терминал перед сборкой

3. Устранение неполадок Docker

3.1 Ошибка: pull access denied или таймаут загрузки

GitHub Container Registry и Docker Hub ограничены или заблокированы в некоторых регионах.

# Вариант A: настроить зеркало реестра (редактировать в Docker Desktop → Settings → Docker Engine)
# Добавить поле JSON:
# "registry-mirrors": ["https://mirror.gcr.io","https://docker.mirrors.ustc.edu.cn"]

# Вариант B: экспортировать образ на машине с сетевым доступом и передать на целевую
docker save ghcr.io/tinyhumansai/openhuman:latest | gzip > openhuman.tar.gz
# Импортировать на целевой машине
gunzip -c openhuman.tar.gz | docker load

3.2 Ошибка: несовместимость платформ (linux/amd64 vs linux/arm64)

При использовании официального образа amd64 на Mac с Apple Silicon возникает это предупреждение.

# Скачать с явным указанием платформы (активирует эмуляцию Rosetta, потеря производительности)
docker pull --platform linux/amd64 ghcr.io/tinyhumansai/openhuman:latest

# Если есть официальный образ arm64, отдать предпочтение нативному
docker pull --platform linux/arm64 ghcr.io/tinyhumansai/openhuman:latest

# Указать платформу при запуске
docker run --platform linux/arm64 ghcr.io/tinyhumansai/openhuman:latest

3.3 Ошибка: permission denied — контейнер не может писать в том

Процесс контейнера запускается от имени непривилегированного пользователя, но подмонтированный хост-каталог принадлежит root.

# Вариант A: открыть права хост-директории для пользователя контейнера (uid обычно 1000)
sudo chown -R 1000:1000 ./openhuman-data

# Вариант B: запустить docker run от root (только для разработки, не для продакшена)
docker run --user root ...

# Вариант C: указать user в Docker Compose
# services:
#   openhuman:
#     user: "1000:1000"
#     volumes:
#       - ./openhuman-data:/app/data

3.4 Ошибка: exec: "sh": executable file not found

Образ использует базу distroless или scratch — оболочка отсутствует.

# Войти в контейнер по полному пути к bash (если он существует)
docker exec -it openhuman /bin/bash

# Если в образе нет shell, собрать отладочный образ и смонтировать исходный том данных
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

База данных или сервис векторного индекса OpenHuman запускается медленно, и проверка работоспособности завершается неудачей.

# Добавить healthcheck для зависимых сервисов в compose.yml
# services:
#   db:
#     healthcheck:
#       test: ["CMD", "pg_isready", "-U", "openhuman"]
#       interval: 5s
#       retries: 10
#   openhuman:
#     depends_on:
#       db:
#         condition: service_healthy

# Вручную просмотреть логи каждого сервиса для определения первопричины
docker compose logs --tail=50 db
docker compose logs --tail=50 openhuman

4. Устранение неполадок Node.js

4.1 Ошибка: The engine "node" is incompatible with this module

Фронтенд и слой плагинов OpenHuman обычно требует Node.js ≥ 20 LTS.

# Переключиться на нужную версию через nvm (рекомендуется LTS 20 или 22)
nvm install 20
nvm use 20
node --version  # подтвердить вывод v20.x.x

# При использовании fnm (более быстрый менеджер версий)
fnm install 20
fnm use 20

4.2 Ошибка: gyp ERR! build error — сбой сборки нативного модуля

Зависимости, такие как better-sqlite3, содержат нативные C++ аддоны и требуют полной цепочки инструментов сборки.

# macOS: убедиться, что Xcode CLT установлены
xcode-select --install

# Windows: установить node-gyp глобально в PowerShell (от имени администратора)
npm install -g node-gyp
# Также убедиться, что Visual Studio Build Tools установлен (см. раздел 2.2)

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

# Принудительно пересобрать все нативные модули
npm rebuild
# Или с pnpm
pnpm rebuild

4.3 Ошибка: Cannot find module ERR_MODULE_NOT_FOUND

Неполная установка зависимостей или кэш node_modules не синхронизирован с lockfile.

# Полная очистка и переустановка
rm -rf node_modules
rm package-lock.json   # или pnpm-lock.yaml / yarn.lock

# Переустановить с помощью пакетного менеджера проекта (пример с pnpm)
corepack enable
pnpm install --frozen-lockfile

4.4 Ошибка: ENOSPC: System limit for number of file watchers reached

Стандартный лимит inotify-наблюдателей в Linux слишком мал.

# Временно увеличить (сбросится после перезагрузки)
sudo sysctl fs.inotify.max_user_watches=524288

# Сохранить настройку навсегда
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

4.5 Ошибка: EACCES: permission denied, mkdir '.../.npm'

Проблемы с правами доступа к глобальному каталогу npm.

# Изменить глобальную директорию npm на доступную для записи пользователю
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# Добавить export выше в ~/.zshrc или ~/.bashrc для постоянного применения

5. Общий чеклист устранения неполадок

Независимо от платформы, при блокировке сначала пройдите этот список по порядку:

6. Всё ещё не решено? Следующие шаги

• Поиск в трекере задач: Найдите ключевые слова ошибки в GitHub Issues.
• Создание подробного Issue: Вставьте вывод cargo build 2>&1 | head -100 вместе с rustup show, node --version и версией ОС.
• Переключение на Docker: Если нативная установка продолжает давать сбои, контейнер Docker — самый быстрый способ обойти различия в окружении.
• Внешний бэкенд вывода: Если локальных ресурсов недостаточно, направьте конечную точку модели OpenHuman на удалённый экземпляр Ollama.

По паттерну «не могу установить локально → использую удалённый Mac-узел» смотрите нашу статью База знаний OpenHuman за 20 минут.

7. Вывод

90% проблем с установкой OpenHuman сводятся к трём корневым причинам: неполная цепочка инструментов сборки, несовместимость версий среды выполнения и ограничения прав доступа или сети на платформе. Следуя этому руководству раздел за разделом, вы сможете решить большинство проблем в течение 30 минут.

Если вы просто хотите быстро попробовать OpenHuman, не тратя время на настройку окружения, Docker — самый быстрый стартовый вариант. Для максимальной производительности и полного локального контроля потратьте время на правильную настройку цепочки инструментов Rust и выберите машину Apple Silicon с достаточным объёмом унифицированной памяти.