Руководство по OpenHuman: более удобный в использовании открытый AI-помощник, чем OpenClaw

GitHub: https://github.com/tinyhumansai/openhuman

Обзор проекта

OpenHuman — это открытый исходный код персонального супер-умного AI-помощника. Его ключевая идея — «по-настоящему встроить AI в вашу повседневную жизнь». По сравнению с OpenClaw главное отличие OpenHuman в подходе UI в первую очередь: вам не нужно возиться с конфигурационными файлами или вводить команды — от установки до получения работающего AI-агента достаточно всего нескольких кликов.

У проекта есть несколько особенно удачных особенностей:

• 118+ интеграций OAuth в один клик: Gmail, Notion, GitHub, Slack, Calendar и другие сервисы — достаточно один раз авторизовать, и можно пользоваться
• Дерево памяти + Obsidian Wiki: автоматически сжимает письма, документы и историю чатов в Markdown и сохраняет локально в SQLite и в хранилище Obsidian
• TokenJuice интеллектуальное сжатие: каждый запрос проходит сжатие ещё до того, как попадёт в LLM — потребление токенов может снизиться до 80%
• Встроенная маршрутизация моделей: в рамках одной подписки задачи автоматически распределяются по подходящей модели (для рассуждений, для быстрых ответов или для задач со зрением)
• Нативная поддержка голоса: STT-ввод, TTS-вывод ElevonLabs и синхронизация губ «маскота»

Сложность/время/результат

• Сложность:⭐⭐☆☆☆ (уровень новичка)
• Время: примерно 15–20 минут (от нуля до запуска)
• Результат: настроить локальную установку, освоить интеграции OAuth-сервисов и использование системы памяти

Целевая аудитория

• Разработчики, которые хотят попробовать открытого AI-помощника, но не хотят возиться с настройкой терминала
• Специалисты, работающие с знаниями и нуждающиеся в системе локального управления знаниями
• Пользователи, которым интересен OpenClaw, но кажется, что порог входа немного высок
• Те, кто хочет, чтобы AI автоматически синхронизировал календарь, почту и документы — и экономил время

Основные зависимости и окружение

Обязательное окружение

Дополнительные зависимости для Windows

# Visual Studio C++ Build Tools (включает MSVC v143 и Windows 11 SDK)
# При установке выберите "Default installation"

# LLVM/Clang (зависимость libclang)
# Скачайте Windows x64-версию с https://github.com/llvm/llvm-project/releases
# При установке отметьте "Add LLVM to system PATH for all users"

# CMake
winget install Kitware.CMake

Проверка установки

rustc --version    # должно быть 1.93.0 или выше
cargo --version
clang --version
cmake --version
node --version     # должно быть v24.x.x или выше
pnpm --version     # должно быть 10.10.0

Полная структура проекта

openhuman/
├── app/                         # pnpm workspace: openhuman-app
│   ├── src/                     # исходники React для фронтенда
│   │   ├── components/           # UI-компоненты
│   │   ├── services/            # клиенты API/RPC
│   │   ├── store/               # управление состоянием Redux
│   │   └── utils/               # утилиты
│   ├── src-tauri/               # таури-оболочка для десктопа
│   └── package.json
├── src/                         # ядро на Rust
│   ├── core/                    # уровень передачи (HTTP/JSON-RPC/CLI)
│   │   ├── jsonrpc.rs           # сервер JSON-RPC
│   │   ├── cli.rs              # интерфейс командной строки
│   │   └── event_bus/           # event bus (шина событий)
│   └── openhuman/              # предметная область (business domain)
│       ├── memory/             # система памяти
│       ├── tokenjuice/         # Token сжатие
│       ├── integrations/       # OAuth-интеграции
│       └── ...
├── scripts/                     # скрипты установки и отладки
│   ├── install.sh              # one-click установка macOS/Linux
│   ├── install.ps1             # one-click установка Windows
│   └── load-dotenv.sh          # загрузка переменных окружения
├── gitbooks/                    # официальная документация
├── Cargo.toml                   # настройки зависимостей Rust
└── package.json                 # настройки зависимостей Node

Пошаговая инструкция

Шаг 1: установка в один клик

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash

Windows

irm https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.ps1 | iex

Установочный скрипт автоматически определит окружение вашей системы и скачает бинарники для соответствующей платформы (DMG/EXE).

Шаг 2: сборка из исходников (опционально)

Если вы хотите поучаствовать в разработке или использовать самые новые возможности:

# 1. Сделайте fork и клонируйте репозиторий
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

# 2. Инициализируйте подмодули
git submodule update --init --recursive

# 3. Установите зависимости
pnpm install

# 4. Разработка только Web UI
pnpm dev

# 5. Разработка полноценного десктопного приложения
pnpm dev:app

Шаг 3: настройка API Key

Скопируйте шаблон переменных окружения:

cp .env.example .env

Отредактируйте файл .env и укажите вашего провайдера LLM:

# Выберите одного или нескольких провайдеров моделей

# Claude (рекомендуется)
ANTHROPIC_API_KEY=sk-ant-xxxxx

# OpenAI GPT
OPENAI_API_KEY=sk-xxxxx

# Google Gemini
GEMINI_API_KEY=xxxxx

Шаг 3.5: Defapi — снижение затрат (рекомендуется)

Если официальный API вам кажется дорогим, можно использовать Defapi — промежуточный сервис, совместимый с OpenAI v1/chat/completions, где цены ниже примерно вдвое.

Defapi поддерживает следующие протоколы:

• v1/chat/completions интерфейс (OpenAI совместимый)
• v1/messages интерфейс (Anthropic совместимый)
• v1beta/models/ интерфейс для списка моделей

Настройка очень простая: нужно заменить адрес официального API на endpoint Defapi и использовать соответствующий ключ:

# Пример настройки Defapi
ANTHROPIC_API_KEY=dk-xxxxx        # ключ Defapi, префикс dk-
OPENAI_API_KEY=dk-xxxxx

# или через base_url (если OpenHuman поддерживает)
ANTHROPIC_BASE_URL=https://api.defapi.org/v1
OPENAI_BASE_URL=https://api.defapi.org/v1/chat

Шаг 4: интеграция OAuth-сервисов

После запуска приложения в интерфейсе:

1. Перейдите в Settings → Integrations
2. Нажмите на сервис, который хотите интегрировать (Gmail, Notion, GitHub и т.д.)
3. Завершите OAuth-процесс авторизации

Или настройте через переменные окружения:

# Gmail OAuth
GMAIL_CLIENT_ID=xxxxx
GMAIL_CLIENT_SECRET=xxxxx

# GitHub OAuth
GITHUB_CLIENT_ID=xxxxx
GITHUB_CLIENT_SECRET=xxxxx

Шаг 5: настройка системы памяти

Система памяти OpenHuman автоматически синхронизирует ваши данные. Ключевые параметры:

# Интервал синхронизации памяти (по умолчанию 20 минут)
OPENHUMAN_MEMORY_SYNC_INTERVAL=20

# Путь к хранилищу Obsidian
OPENHUMAN_OBSIDIAN_VAULT_PATH=~/Documents/openhuman-vault

# Уровень сжатия TokenJuice
OPENHUMAN_TOKENJUICE_COMPRESSION=high

Данные памяти хранятся локально в SQLite:

# Путь по умолчанию
~/.openhuman/memory.db

Шаг 6: запуск и проверка

Десктопное приложение

# macOS
open -a OpenHuman

# Linux
openhuman-app

# Windows
OpenHuman.exe

Режим CLI

# Запуск основного сервиса
openhuman serve

# Интерактивный диалог
openhuman run

Проверка состояния запуска

# Проверить health
curl http://127.0.0.1:7788/health

# Посмотреть основной токен
cat ~/.openhuman/core.token

Частые проблемы и способы устранения

1. Ошибка в установочном скрипте: "command not found"

Убедитесь, что в системе установлен curl и нужные сетевые утилиты:

# macOS
brew install curl

# Ubuntu/Debian
sudo apt install curl

# Windows (PowerShell 7+)
scoop install curl

2. Десктопное приложение не запускается

Проверьте зависимости Tauri:

# Проверка только для Windows
$env:LIBCLANG_PATH = "C:\\Program Files\\LLVM\\bin"
clang -v
cmake --version

Убедитесь, что установлен Visual Studio Build Tools и включена рабочая нагрузка «Desktop development with C++».

3. Ошибка OAuth-авторизации

Проверьте, что callback URL указан корректно:

http://localhost:7788/oauth/callback

Добавьте этот redirect URI в настройках OAuth-приложения.

4. Синхронизация памяти не работает

Проверьте шаги:

# 1. Проверить логи ядра
tail -f ~/.openhuman/logs/core.log

# 2. Вручную запустить синхронизацию
openhuman memory sync

# 3. Убедиться, что хранилище Obsidian доступно для записи
ls -la ~/Documents/openhuman-vault

5. TokenJuice-сжатие неэффективно

Подтвердите, что сжатие включено:

# В .env
OPENHUMAN_TOKENJUICE_ENABLED=true
OPENHUMAN_TOKENJUICE_LEVEL=high

# Перезапустить основной сервис
openhuman restart

6. Маршрутизация моделей не применяется

Проверьте настройки модели:

# Посмотреть текущую конфигурацию модели
openhuman config show

# Явно указать модель
OPENHUMAN_MODEL=claude-sonnet-4-20250514

7. Ошибки при подключении к Defapi (например, 401)

Если вы используете Defapi и получаете ошибки подключения или 401:

# 1. Убедитесь, что ключ имеет правильный формат (у Defapi префикс dk-)
# Правильно: ANTHROPIC_API_KEY=dk-1234567890abcdef
# Неправильно: ANTHROPIC_API_KEY=sk-ant-xxxxx (это формат официального ключа)

# 2. Проверьте base_url (если нужно)
ANTHROPIC_BASE_URL=https://api.defapi.org/v1

# 3. Убедитесь, что имя модели поддерживается Defapi
# Формат: developer/model (например, anthropic/claude-sonnet-4.5)

# 4. Проверьте работоспособность Defapi
curl https://api.defapi.org/v1/models \
  -H "Authorization: Bearer dk-your_key"

Если всё выше выполнено, но ошибка остаётся — проверьте состояние аккаунта и баланс на сайте Defapi.

Дальнейшее чтение

• Официальная документация — полная документация в GitBook
• Дизайн архитектуры — подробнее об архитектуре системы
• backend агентной памяти — общая память для Claude Code/Cursor
• Настройки маршрутизации моделей — как оптимизировать выбор модели
• Автозагрузка (auto-fetch) — принцип автоматической синхронизации каждые 20 минут

---

Связанные проекты

• OpenClaw — ещё один популярный open source AI Agent
• agentmemory — общий backend памяти
• Obsidian — инструмент для локальной базы знаний