OpenHuman 入门指南: 比 OpenClaw 更易用的开源 AI 助手

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 之前都会经过压缩，token 消耗最多能降低 80%
内置模型路由：一个订阅下自动分派任务到合适的模型（推理型、快速型或视觉型）
原生语音支持：STT 输入、ElevonLabs TTS 输出、吉祥物口型同步

TIP

如果你用过 OpenClaw，会发现 OpenHuman 更适合「不想折腾」的普通用户——它的开箱即用体验更接近商业产品。

难度/时长/收获

难度：⭐⭐☆☆☆（入门级）
时长：约 15-20 分钟（从零到跑起来）
收获：掌握本地安装配置、OAuth 服务集成、记忆系统使用

目标读者

想尝试开源 AI 助手但不想折腾终端配置的开发者
需要本地知识管理系统的知识工作者
对 OpenClaw 感兴趣但觉得门槛略高的用户
希望 AI 能自动同步日历、邮件、文档的效率党

核心依赖与环境

必需环境

依赖	版本要求	说明
Node.js	>= 24.0.0	前端开发必需
pnpm	10.10.0	项目管理器
Rust	1.93.0	核心运行时
CMake	最新稳定版	Rust 原生依赖
Ninja	最新稳定版	macOS CEF 构建必需

Windows 额外依赖

# Visual Studio C++ Build Tools (包含 MSVC v143 和 Windows 11 SDK)
# 安装时选择 "Default installation"

# LLVM/Clang (libclang 依赖)
# 下载 https://github.com/llvm/llvm-project/releases 的 Windows x64 版本
# 安装时勾选 "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/               # Tauri 桌面壳
│   └── package.json
├── src/                         # Rust 核心库
│   ├── core/                    # 传输层 (HTTP/JSON-RPC/CLI)
│   │   ├── jsonrpc.rs           # JSON-RPC 服务端
│   │   ├── cli.rs              # 命令行接口
│   │   └── event_bus/           # 事件总线
│   └── openhuman/              # 业务域
│       ├── memory/             # 记忆系统
│       ├── tokenjuice/         # Token 压缩
│       ├── integrations/       # OAuth 集成
│       └── ...
├── scripts/                     # 安装和调试脚本
│   ├── install.sh              # macOS/Linux 一键安装
│   ├── install.ps1             # 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

WARNING

API Key 会存储在本地，确保 .env 文件不要提交到 git 仓库。

步骤 3.5：使用 Defapi 降低成本（推荐）

如果你觉得官方 API 价格偏高，可以考虑 Defapi——一个兼容 OpenAI v1/chat/completions 协议的中转平台，价格只有官方的一半。

Defapi 支持以下协议：

v1/chat/completions 接口（OpenAI 兼容）
v1/messages 接口（Anthropic 兼容）
v1beta/models/ 模型列表接口

配置非常简单，只需要把官方 API 地址换成 Defapi 的端点，同时更换 API Key：

# Defapi 配置示例
ANTHROPIC_API_KEY=dk-xxxxx        # Defapi 的 Key，格式为 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

Defapi 支持的模型包括：

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

TIP

OpenHuman 内置的 TokenJuice 压缩和 Defapi 的低价策略配合使用，长期下来能省不少银子。具体模型价格可以在 Defapi 官网查看。

步骤 4：OAuth 服务集成

启动应用后，在界面中：

进入 Settings → Integrations
点击想集成的服务（Gmail、Notion、GitHub 等）
完成 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

验证运行状态

# 检查健康状态
curl http://127.0.0.1:7788/health

# 查看核心 token
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 授权失败

检查回调 URL 是否正确配置：

http://localhost:7788/oauth/callback

在 OAuth 应用设置中添加这个重定向 URI。

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 却遇到连接问题：

# 1. 确认 API Key 格式正确（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-你的Key"

如果以上都没问题但仍然报错，可以到 Defapi 官网确认你的账户状态和余额。

扩展阅读

官方文档 — 完整的 GitBook 文档
架构设计 — 深入了解系统架构
agentmemory 后端 — 与 Claude Code/Cursor 共用记忆
模型路由配置 — 如何优化模型选择
自动拉取功能 — 20 分钟自动同步原理
Defapi 官网 — API 中转平台，价格只有官方的一半

相关项目

OpenClaw — 另一个流行的开源 AI Agent
agentmemory — 共享记忆后端
Obsidian — 本地知识库工具