Guia de Início do OpenHuman: um assistente de IA de código aberto ainda mais fácil de usar que o OpenClaw

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

Visão geral do projeto

OpenHuman é um superassistente pessoal de IA de código aberto, cuja ideia central é «integrar de verdade a IA no seu dia a dia». Em comparação com o OpenClaw, a maior diferença do OpenHuman é o design com prioridade na UI — você não precisa ficar mexendo em arquivos de configuração nem digitando comandos. Do processo de instalação até ter um agente de IA funcional, são necessárias apenas algumas cliques.

O projeto traz alguns recursos que chamam a atenção:

Integração instantânea com 118+ OAuth: Gmail, Notion, GitHub, Slack, Calendar e outros serviços — basta autorizar em um clique
Árvore de memórias + Obsidian Wiki: comprime automaticamente e-mails, documentos e histórico de chats em Markdown, salvando localmente em um SQLite e em um repositório do Obsidian
TokenJuice compressão inteligente: cada solicitação passa por compressão antes de chegar ao LLM; o consumo de tokens pode ser reduzido em até 80%
Roteamento nativo de modelos: em uma única assinatura, as tarefas são automaticamente distribuídas para o modelo mais adequado (de inferência, rápido ou visual)
Suporte nativo a voz: entrada STT, saída TTS via ElevonLabs e sincronização labial do mascote

TIP

Se você já usou o OpenClaw, vai perceber que o OpenHuman é mais adequado para usuários comuns que «não querem ter trabalho» — a experiência “pronto para usar” fica mais próxima de produtos comerciais.

Dificuldade/Duração/Benefícios

Dificuldade: ⭐⭐☆☆☆ (nível iniciante)
Duração: cerca de 15-20 minutos (do zero até funcionar)
Benefícios: aprender a instalar/configurar localmente, integrar serviços via OAuth e usar o sistema de memórias

Público-alvo

Desenvolvedores que querem experimentar um assistente de IA de código aberto, mas não querem lidar com configurações do terminal
Profissionais que trabalham com gestão de conhecimento local
Usuários interessados no OpenClaw, mas que acham a barreira um pouco alta
Quem busca eficiência: quer que a IA sincronize automaticamente calendário, e-mails e documentos

Dependências principais e ambiente

Ambiente necessário

Dependência	Requisito de versão	Descrição
Node.js	>= 24.0.0	Essencial para desenvolvimento de front-end
pnpm	10.10.0	Gerenciador de projeto
Rust	1.93.0	Runtime principal
CMake	versão estável mais recente	Dependências nativas do Rust
Ninja	versão estável mais recente	Necessário para build do CEF no macOS

Dependências extras no Windows

# Visual Studio C++ Build Tools (inclui MSVC v143 e Windows 11 SDK)
# Durante a instalação, selecione "Default installation"

# LLVM/Clang (depende de libclang)
# Baixe a versão para Windows x64 em https://github.com/llvm/llvm-project/releases
# Durante a instalação, marque "Add LLVM to system PATH for all users"

# CMake
winget install Kitware.CMake

Verificação da instalação

rustc --version    # deve exibir 1.93.0 ou superior
cargo --version
clang --version
cmake --version
node --version     # deve exibir v24.x.x ou superior
pnpm --version     # deve exibir 10.10.0

Estrutura completa do projeto

openhuman/
├── app/                         # pnpm workspace: openhuman-app
│   ├── src/                     # código-fonte do React (front-end)
│   │   ├── components/           # componentes de UI
│   │   ├── services/            # clientes de API/RPC
│   │   ├── store/               # gerenciamento de estado Redux
│   │   └── utils/               # funções utilitárias
│   ├── src-tauri/               # container desktop do Tauri
│   └── package.json
├── src/                         # biblioteca central em Rust
│   ├── core/                    # camada de transporte (HTTP/JSON-RPC/CLI)
│   │   ├── jsonrpc.rs           # servidor JSON-RPC
│   │   ├── cli.rs              # interface de linha de comando
│   │   └── event_bus/           # barramento de eventos
│   └── openhuman/              # domínio da aplicação
│       ├── memory/             # sistema de memórias
│       ├── tokenjuice/         # compressão de tokens
│       ├── integrations/       # integrações OAuth
│       └── ...
├── scripts/                     # scripts de instalação e depuração
│   ├── install.sh              # instalação “one-click” para macOS/Linux
│   ├── install.ps1             # instalação “one-click” para Windows
│   └── load-dotenv.sh          # carregamento de variáveis de ambiente
├── gitbooks/                    # documentação oficial
├── Cargo.toml                   # configuração de dependências Rust
└── package.json                 # configuração de dependências Node

Passo a passo

Passo 1: instalação em um clique

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

O script de instalação detecta automaticamente o ambiente do seu sistema, baixando os binários correspondentes à sua plataforma (DMG/EXE).

Passo 2: compilar a partir do código-fonte (opcional)

Se você quiser participar do desenvolvimento ou usar os recursos mais recentes:

# 1. Faça um Fork e clone o repositório
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

# 2. Inicialize os submódulos
git submodule update --init --recursive

# 3. Instale as dependências
pnpm install

# 4. Desenvolvimento apenas para Web UI
pnpm dev

# 5. Desenvolvimento de aplicativo desktop completo
pnpm dev:app

Passo 3: configurar a API Key

Copie o modelo de variáveis de ambiente:

cp .env.example .env

Edite o arquivo .env para configurar seu provedor de LLM:

# Selecione um ou mais provedores de modelos

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

# OpenAI GPT
OPENAI_API_KEY=sk-xxxxx

# Google Gemini
GEMINI_API_KEY=xxxxx

WARNING

A API Key será armazenada localmente; certifique-se de que o arquivo .env não seja enviado para o repositório git.

Passo 3.5: usar Defapi para reduzir custos (recomendado)

Se você achar que os preços da API oficial estão altos, considere Defapi — uma plataforma de proxy compatível com o protocolo OpenAI v1/chat/completions, com preços pela metade.

O Defapi suporta os seguintes protocolos:

v1/chat/completions (compatível com OpenAI)
v1/messages (compatível com Anthropic)
v1beta/models/ (lista de modelos)

A configuração é bem simples: basta trocar a URL da API oficial pela do Defapi e usar uma nova API Key.

# Exemplo de configuração Defapi
ANTHROPIC_API_KEY=dk-xxxxx        # Key do Defapi, com prefixo dk-
OPENAI_API_KEY=dk-xxxxx

# Ou, se o OpenHuman suportar, especifique o endpoint via base_url
ANTHROPIC_BASE_URL=https://api.defapi.org/v1
OPENAI_BASE_URL=https://api.defapi.org/v1/chat

TIP

O OpenHuman já faz a compressão TokenJuice e, ao combinar isso com a política de preços mais baixos do Defapi, dá para economizar bastante no longo prazo. Para conferir preços e modelos compatíveis, veja o site do Defapi.

O Defapi suporta modelos como:

anthropic/claude-sonnet-4.5 / claude-opus-4.5 / claude-haiku-4.5
openai/gpt-4o / gpt-4o-mini / gpt-5
google/gemini-3-flash

Passo 4: integração via OAuth

Após iniciar o aplicativo, no painel:

Vá em Settings → Integrations
Clique no serviço que você deseja integrar (Gmail, Notion, GitHub etc.)
Conclua o fluxo de autorização do OAuth

Ou configure via variáveis de ambiente:

# Gmail OAuth
GMAIL_CLIENT_ID=xxxxx
GMAIL_CLIENT_SECRET=xxxxx

# GitHub OAuth
GITHUB_CLIENT_ID=xxxxx
GITHUB_CLIENT_SECRET=xxxxx

Passo 5: configurar o sistema de memórias

O sistema de memórias do OpenHuman sincroniza automaticamente seus dados. Itens de configuração principais:

# Intervalo de sincronização das memórias (padrão: 20 minutos)
OPENHUMAN_MEMORY_SYNC_INTERVAL=20

# Caminho do vault do Obsidian
OPENHUMAN_OBSIDIAN_VAULT_PATH=~/Documents/openhuman-vault

# Nível de compressão do TokenJuice
OPENHUMAN_TOKENJUICE_COMPRESSION=high

Os dados das memórias ficam armazenados localmente em um SQLite:

# Caminho padrão de armazenamento
~/.openhuman/memory.db

Passo 6: iniciar e validar

Aplicativo desktop

# macOS
open -a OpenHuman

# Linux
openhuman-app

# Windows
OpenHuman.exe

Modo CLI

# Iniciar o serviço principal
openhuman serve

# Conversa em modo interativo
openhuman run

Validar o status de execução

# Verificar o health
curl http://127.0.0.1:7788/health

# Visualizar token principal
cat ~/.openhuman/core.token

Solução de problemas frequentes

1. O script de instalação retorna erro «command not found»

Certifique-se de que curl e as ferramentas de rede necessárias já estão instaladas:

# macOS
brew install curl

# Ubuntu/Debian
sudo apt install curl

# Windows (PowerShell 7+)
scoop install curl

2. Falha ao iniciar o aplicativo desktop

Verifique as dependências do ambiente Tauri:

# Verificação específica para Windows
$env:LIBCLANG_PATH = "C:\\Program Files\\LLVM\\bin"
clang -v
cmake --version

Confirme que o Visual Studio Build Tools está instalado e que inclui o workload «Desktop development with C++».

3. Falha na autorização OAuth

Verifique se a URL de callback está configurada corretamente:

http://localhost:7788/oauth/callback

Adicione esse URI de redirecionamento nas configurações do aplicativo OAuth.

4. Sincronização de memórias não funciona

Siga a investigação:

# 1. Verificar logs do core
tail -f ~/.openhuman/logs/core.log

# 2. Acionar a sincronização manualmente
openhuman memory sync

# 3. Confirmar que o vault do Obsidian é gravável
ls -la ~/Documents/openhuman-vault

5. Compressão TokenJuice não funciona

Verifique se a compressão está habilitada:

# Definir no .env
OPENHUMAN_TOKENJUICE_ENABLED=true
OPENHUMAN_TOKENJUICE_LEVEL=high

# Reiniciar o serviço principal
openhuman restart

6. O roteamento de modelos não é aplicado

Verifique a configuração do modelo:

# Ver a configuração atual
openhuman config show

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

7. Erro no Defapi (falha na conexão ou 401)

Se você usa o Defapi e está tendo problemas de conexão ou recebendo 401:

# 1. Confirme se o formato da API Key está correto (Defapi usa prefixo dk-)
# Correto: ANTHROPIC_API_KEY=dk-1234567890abcdef
# Errado: ANTHROPIC_API_KEY=sk-ant-xxxxx (isso é o formato da API oficial)

# 2. Confirme se o base_url está correto (se não for o padrão)
ANTHROPIC_BASE_URL=https://api.defapi.org/v1

# 3. Verifique se o nome do modelo está na lista de modelos suportados pelo Defapi
# Formato esperado: developer/model, ex.: anthropic/claude-sonnet-4.5

# 4. Teste a conectividade do Defapi
curl https://api.defapi.org/v1/models \\
  -H "Authorization: Bearer dk-CHAVE_SUA"

Se as etapas acima estiverem corretas, mas o erro continuar, confirme com o suporte do Defapi o status da sua conta e o saldo.

Leitura adicional

Documentação oficial — documentação completa no GitBook
Design da arquitetura — visão aprofundada da arquitetura do sistema
Backend do agentmemory — memórias compartilhadas com Claude Code/Cursor
Configuração de roteamento de modelos — como otimizar a escolha do modelo
Recurso de sincronização automática — princípio da sincronização automática a cada 20 minutos

Projetos relacionados

OpenClaw — outro agente de IA open source popular
agentmemory — backend de memórias compartilhadas
Obsidian — ferramenta de base de conhecimento local