Guía de inicio de OpenHuman: un asistente de IA de código abierto más fácil de usar que OpenClaw

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

Descripción del proyecto

OpenHuman es un asistente personal de IA de súper alta inteligencia, de código abierto, cuya idea central es «integrar la IA de verdad en tu vida diaria». En comparación con OpenClaw, la mayor diferencia de OpenHuman es su enfoque de diseño: prioriza la interfaz de usuario. No necesitas pelearte con archivos de configuración ni escribir comandos; desde la instalación hasta tener un agente de IA funcional solo necesitas hacer unas pocas clics.

El proyecto tiene varias características que sorprenden:

Integración con OAuth en un clic (118+): Gmail, Notion, GitHub, Slack, Calendar y más, con autorización de un solo paso para empezar
Árbol de memoria + Obsidian Wiki: comprime automáticamente correos, documentos y chats en Markdown, y los guarda localmente en SQLite y en tu repositorio de Obsidian
TokenJuice: compresión inteligente: cada solicitud pasa por un proceso de compresión antes de llegar al LLM; el consumo de tokens puede reducirse hasta un 80%
Enrutado de modelos integrado: bajo una sola suscripción, asigna tareas automáticamente al modelo adecuado (de razonamiento, rápido o visual)
Soporte nativo de voz: entrada STT, salida TTS con ElevonLabs y sincronización labial del “mascota”

TIP

Si has usado OpenClaw, verás que OpenHuman está mejor pensado para los usuarios comunes que «no quieren complicarse»; su experiencia “lista para usar” se parece más a la de un producto comercial.

Dificultad / duración / resultado

Dificultad: ⭐⭐⭐☆☆（nivel inicial）
Duración: unos 15-20 minutos (de cero a funcionando)
Resultado: dominar la instalación y configuración local, la integración de servicios con OAuth y el uso del sistema de memoria

Público objetivo

Desarrolladores que quieren probar asistentes de IA de código abierto pero no quieren pelearse con configuraciones del terminal
Trabajadores del conocimiento que necesitan un sistema local de gestión de conocimiento
Usuarios interesados en OpenClaw, pero que consideran que la barrera de entrada es un poco alta
Personas orientadas a la eficiencia que quieren que la IA sincronice automáticamente calendario, correos y documentos

Dependencias principales y entorno

Entorno requerido

Dependencia	Requisito de versión	Descripción
Node.js	>= 24.0.0	imprescindible para desarrollo de frontend
pnpm	10.10.0	gestor de proyectos
Rust	1.93.0	runtime principal
CMake	la versión estable más reciente	dependencias nativas de Rust
Ninja	la versión estable más reciente	necesario para construir CEF en macOS

Dependencias adicionales en Windows

# Herramientas de Build de Visual Studio C++ (incluye MSVC v143 y Windows 11 SDK)
# Al instalar, elige "Default installation"

# LLVM/Clang (depende de libclang)
# Descarga la versión para Windows x64 desde https://github.com/llvm/llvm-project/releases
# Al instalar, marca "Add LLVM to system PATH for all users"

# CMake
winget install Kitware.CMake

Verificación de la instalación

rustc --version    # debería mostrar 1.93.0 o superior
cargo --version
clang --version
cmake --version
node --version     # debería mostrar v24.x.x o superior
pnpm --version     # debería mostrar 10.10.0

Estructura completa del proyecto

openhuman/
├── app/                         # pnpm workspace: openhuman-app
│   ├── src/                     # código fuente del frontend React
│   │   ├── components/           # componentes de UI
│   │   ├── services/            # cliente API/RPC
│   │   ├── store/               # gestión de estado Redux
│   │   └── utils/               # funciones de utilidades
│   ├── src-tauri/               # “shell” de escritorio Tauri
│   └── package.json
├── src/                         # librería central en Rust
│   ├── core/                    # capa de transporte (HTTP/JSON-RPC/CLI)
│   │   ├── jsonrpc.rs           # servidor JSON-RPC
│   │   ├── cli.rs              # interfaz de línea de comandos
│   │   └── event_bus/           # bus de eventos
│   └── openhuman/              # dominio del negocio
│       ├── memory/             # sistema de memoria
│       ├── tokenjuice/         # compresión de tokens
│       ├── integrations/       # integraciones OAuth
│       └── ...
├── scripts/                     # scripts de instalación y depuración
│   ├── install.sh              # instalación en un clic para macOS/Linux
│   ├── install.ps1             # instalación en un clic para Windows
│   └── load-dotenv.sh          # carga de variables de entorno
├── gitbooks/                    # documentación oficial
├── Cargo.toml                   # configuración de dependencias de Rust
└── package.json                 # configuración de dependencias de Node

Pasos guiados

Paso 1: Instalación en un clic

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

El script de instalación detectará automáticamente el entorno de tu sistema y descargará los binarios correspondientes de cada plataforma (DMG/EXE).

Paso 2: Compilar desde el código fuente (opcional)

Si quieres contribuir al desarrollo o usar las funciones más recientes:

# 1. Haz un Fork y clona el repositorio
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

# 2. Inicializa los submódulos
git submodule update --init --recursive

# 3. Instala dependencias
pnpm install

# 4. Desarrollo solo con Web UI
pnpm dev

# 5. Desarrollo de aplicación de escritorio completa
pnpm dev:app

Paso 3: Configurar la API Key

Copia la plantilla de variables de entorno:

cp .env.example .env

Edita el archivo .env para configurar tu proveedor de LLM:

# Elige uno o varios proveedores de modelos

# Claude (recomendado)
ANTHROPIC_API_KEY=sk-ant-xxxxx

# OpenAI GPT
OPENAI_API_KEY=sk-xxxxx

# Google Gemini
GEMINI_API_KEY=xxxxx

WARNING

La API Key se almacenará localmente; asegúrate de que el archivo .env no se suba al repositorio git.

Paso 3.5: Usar Defapi para reducir costes (recomendado)

Si te parece que el precio de la API oficial es alto, puedes considerar Defapi. Se trata de una plataforma de intermediación compatible con el protocolo OpenAI v1/chat/completions, con un coste que es aproximadamente la mitad.

Defapi admite los siguientes protocolos:

v1/chat/completions (compatible con OpenAI)
v1/messages (compatible con Anthropic)
v1beta/models/ (lista de modelos)

La configuración es sencilla: solo tienes que sustituir la URL de la API oficial por el endpoint de Defapi y cambiar tu API Key.

# Ejemplo de configuración con Defapi
ANTHROPIC_API_KEY=dk-xxxxx        # Key de Defapi (prefijo dk-)
OPENAI_API_KEY=dk-xxxxx

# O mediante base_url (si OpenHuman lo permite)
ANTHROPIC_BASE_URL=https://api.defapi.org/v1
OPENAI_BASE_URL=https://api.defapi.org/v1/chat

TIP

La compresión TokenJuice integrada de OpenHuman y la estrategia de precios más baja de Defapi se combinan muy bien; a largo plazo puedes ahorrar bastante dinero. Los precios concretos de cada modelo puedes consultarlos en la web de Defapi.

Paso 4: Integración del servicio OAuth

Tras iniciar la aplicación, en la interfaz:

Ve a Settings → Integrations
Haz clic en el servicio que quieras integrar (Gmail, Notion, GitHub, etc.)
Completa el flujo de autorización OAuth

O bien, configura mediante variables de entorno:

# Gmail OAuth
GMAIL_CLIENT_ID=xxxxx
GMAIL_CLIENT_SECRET=xxxxx

# GitHub OAuth
GITHUB_CLIENT_ID=xxxxx
GITHUB_CLIENT_SECRET=xxxxx

Paso 5: Configurar el sistema de memoria

El sistema de memoria de OpenHuman sincroniza automáticamente tus datos. Las opciones de configuración clave:

# Intervalo de sincronización de memoria (por defecto: 20 minutos)
OPENHUMAN_MEMORY_SYNC_INTERVAL=20

# Ruta del repositorio de Obsidian
OPENHUMAN_OBSIDIAN_VAULT_PATH=~/Documents/openhuman-vault

# Nivel de compresión TokenJuice
OPENHUMAN_TOKENJUICE_COMPRESSION=high

Los datos de memoria se almacenan en SQLite local:

# Ruta de almacenamiento predeterminada
~/.openhuman/memory.db

Paso 6: Iniciar y verificar

Aplicación de escritorio

# macOS
open -a OpenHuman

# Linux
openhuman-app

# Windows
OpenHuman.exe

Modo CLI

# Inicia el servicio central
openhuman serve

# Diálogo interactivo
openhuman run

Verificar el estado de ejecución

# Comprobar el estado de salud
curl http://127.0.0.1:7788/health

# Ver el token central
cat ~/.openhuman/core.token

Solución de problemas frecuentes

1. El script de instalación falla con "command not found"

Asegúrate de que tu sistema tenga instalado curl y las herramientas de red necesarias:

# macOS
brew install curl

# Ubuntu/Debian
sudo apt install curl

# Windows (PowerShell 7+)
scoop install curl

2. La aplicación de escritorio no se inicia

Revisa las dependencias del entorno de Tauri:

# Comprobación específica para Windows
$env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin"
clang -v
cmake --version

Asegúrate de que las Visual Studio Build Tools estén instaladas e incluyan la carga de trabajo "Desktop development with C++".

3. Falla la autorización OAuth

Verifica que la URL de callback esté configurada correctamente:

http://localhost:7788/oauth/callback

En la configuración de la aplicación OAuth, añade este URI de redirección.

4. La sincronización de memoria no funciona

Pasos de diagnóstico:

# 1. Revisa el log central
tail -f ~/.openhuman/logs/core.log

# 2. Disparar la sincronización manualmente
openhuman memory sync

# 3. Verifica que el repositorio de Obsidian sea escribible
ls -la ~/Documents/openhuman-vault

5. La compresión TokenJuice no funciona

Confirma que la compresión esté activada:

# En el .env
OPENHUMAN_TOKENJUICE_ENABLED=true
OPENHUMAN_TOKENJUICE_LEVEL=high

# Reinicia el servicio central
openhuman restart

6. El enrutado de modelos no tiene efecto

Revisa la configuración de modelos:

# Revisa la configuración actual de modelos
openhuman config show

# Especificar el modelo manualmente
OPENHUMAN_MODEL=claude-sonnet-4-20250514

7. Falla la conexión a Defapi o aparece un error 401

Si usas Defapi y te encuentras con problemas de conexión o un error 401:

# 1. Confirma que el formato de la API Key sea correcto (Defapi usa prefijo dk-)
# Correcto: ANTHROPIC_API_KEY=dk-1234567890abcdef
# Incorrecto: ANTHROPIC_API_KEY=sk-ant-xxxxx (esto es el formato oficial)

# 2. Confirma que base_url esté bien configurado (si no es el valor predeterminado)
ANTHROPIC_BASE_URL=https://api.defapi.org/v1

# 3. Comprueba que el nombre del modelo esté en la lista de modelos admitidos por Defapi
# El formato del nombre del modelo debe ser: developer/model, por ejemplo anthropic/claude-sonnet-4.5

# 4. Prueba la conectividad con Defapi
curl https://api.defapi.org/v1/models \
  -H "Authorization: Bearer dk-tu_clave"

Si todo lo anterior está correcto pero el error persiste, revisa el estado de tu cuenta y el saldo en la web de Defapi.

Lecturas adicionales

Documentación oficial — documentación completa en GitBook
Diseño de arquitectura — profundiza en la arquitectura del sistema
Backend de agentmemory — memoria compartida para Claude Code/Cursor
Configuración de enrutado de modelos — cómo optimizar la elección de modelos
Función de auto-fetch — principio de la sincronización automática cada 20 minutos

Proyectos relacionados

OpenClaw — otro AI Agent de código abierto popular
agentmemory — backend de memoria compartida
Obsidian — herramienta de repositorio de conocimiento local