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

May 17, 2026

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前端开发必需
pnpm10.10.0项目管理器
Rust1.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 仓库。

步骤 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

验证运行状态

# 检查健康状态
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

进一步阅读

相关项目

Updated May 19, 2026