OpenHuman 安装、使用方法详细全解

GitHub 仓库： https://github.com/tinyhumansai/openhuman
官方文档： https://tinyhumans.gitbook.io/openhuman/
官方网站： https://tinyhumans.ai/openhuman
社区： Discord, Reddit (r/tinyhumansai), X/Twitter (@tinyhumansai)

目录

  1. 项目概述
  2. 核心功能
  3. 系统架构
  4. 安装指南
  5. 使用方法（全面详解）
  6. 配置说明
  7. 云端部署
  8. 开发指南
  9. 对比分析
  10. 安全与隐私
  11. 注意事项与已知问题

1. 项目概述

OpenHuman 是一个开源的个人 AI 超级智能助手，定位为"个人 AI super intelligence"——将你的数据、记忆和行为融入 AI 智能体（Agent），使其能够理解你的工作、生活，并主动为你完成任务。

核心理念

  • 本地优先（Local-first）： 记忆树、Obsidian 风格 Markdown 仓库、工作区配置和本地运行时状态全部存储在你的机器上
  • 简单强大： 从安装到可用只需几分钟，无需先配置，无需终端操作
  • 隐私安全： 工作流数据保留在设备上，本地加密，数据属于你
  • 跨平台： 支持 Windows、macOS、Linux 桌面端

解决的问题

当前所有 AI 模型（200+ 个）都面临一个根本限制：无状态性。你输入提示词，得到回复，上下文就消失了。即使有些声称有"记忆"，也只是存几个要点——那是便利贴，不是真正的智能。

OpenHuman 通过以下技术栈解决这一问题：

  • 记忆树（Memory Tree）—— 结构化知识图谱
  • Obsidian 风格 Wiki —— 可读可编辑的 Markdown 知识仓库
  • 118+ 第三方集成 —— 一键 OAuth 连接你日常使用的工具
  • 自动拉取（Auto-fetch）—— 每 20 分钟自动同步数据到记忆
  • 智能 Token 压缩（TokenJuice）—— 减少 80% 的 Token 消耗

2. 核心功能

2.1 记忆树（Memory Tree）

OpenHuman 的核心差异化功能之一。每个你连接的数据源（Gmail、Slack、GitHub、Notion、个人笔记等）通过一个确定性流水线处理：

  1. 标准化 —— 所有数据转换为 Markdown 格式
  2. 分块 —— 每块 ≤3k token
  3. 评分 —— 按重要性/相关性打分
  4. 折叠 —— 按来源 / 主题 / 日期折叠为层级化摘要树
  5. 存储 —— 存储在本地 SQLite 数据库中

这不是向量搜索的"黑盒子"，而是结构化的、可理解的记忆层次。

2.2 Obsidian 风格 Wiki

  • 所有记忆片段同时以 .md 文件形式落地到兼容 Obsidian 的本地仓库
  • 你可以用 Obsidian 打开、浏览、编辑这些文件
  • 灵感来源于 Karpathy 的 obsidian-wiki 工作流
  • 支持可选的 agentmemory 后端代理

2.3 118+ 第三方集成

通过一键 OAuth 接入你的技术栈：

类别 支持的服务
邮件 Gmail
办公 Notion, Google Drive
开发 GitHub, GitLab
协作 Slack, Google Calendar
项目管理 Linear, Jira
支付 Stripe
消息 Telegram 等

每个连接都被暴露为类型化的工具供 Agent 使用。默认使用 OpenHuman 的 Composio 连接器层，OAuth 握手和工具调用通过托管后端代理。

2.4 自动拉取（Auto-fetch）

  • 每 20 分钟 自动遍历所有活跃连接
  • 将新数据拉取到记忆树中
  • 无需编写轮询循环、无需手动触发
  • 智能体每天早上就已经拥有当天的上下文

2.5 智能 Token 压缩（TokenJuice）

在数据触达 LLM 之前经过压缩层处理：

操作 说明
HTML → Markdown 网页抓取结果自动转换
URL 缩短 长 URL 被压缩
去重摘要 冗长工具输出被去重和摘要
多字节保留 CJK、emoji 等多字节字符按字形完整保留

效果： 相同信息量下，Token 消耗减少高达 80%，显著降低成本和延迟。

2.6 自动模型路由（Model Routing）

  • 默认使用 OpenHuman 后端自动选择和代理适合每个工作负载的 LLM
  • 支持推理型、快速型、视觉型等不同角色
  • 一个订阅包含所有模型
  • 可选本地 AI： 支持通过 Ollama 或 LM Studio 运行端侧模型

2.7 内置工具集（Batteries Included）

工具 说明
网络搜索 内置 Web 搜索能力
网页抓取 Web-fetch 爬虫
编码工具集 文件系统、Git、Lint、测试、Grep
浏览器控制 浏览器和计算机控制
定时任务 Cron 调度器
记忆工具 记忆读写和操作
Agent 协调 多 Agent 协调
原生语音 STT 输入 + ElevenLabs TTS 输出 + 吉祥物口型同步
Google Meet Agent 作为真实参与者加入会议

2.8 桌面吉祥物（Realtime Mascot）

  • 桌面吉祥物会说话、能感知周围环境
  • 可作为真实参与者加入 Google Meet 会议
  • 跨周记住你，在你停止输入后仍在后台持续思考

2.9 潜意识循环（Subconscious Loop）

Agent 在后台持续运行，即使你没有主动输入，它也在：

  • 自动整理和更新记忆树
  • 监控连接的数据源
  • 准备上下文和上下文压缩

2.10 消息渠道（Messaging Channels）

支持通过你日常使用的渠道进行收发，不局限于桌面客户端。

3. 系统架构

3.1 整体架构

+------------------------------------------------------------------+
|                        React 前端                                 |
|  Redux Toolkit | Socket.io Client | MCP Transport | UI           |
+------------------------------------------------------------------+
                          | Tauri IPC Bridge |
+------------------------------------------------------------------+
|                        Rust 核心引擎                               |
|                                                                    |
|  +------------------+  +------------------+  +-----------------+ |
|  |   工具运行时      |  |  Socket 管理器   |  | AI 加密与记忆   | |
|  |  (Native + Node) |  |  (持久 WebSocket)|  |  存储           | |
|  +------------------+  +------------------+  +-----------------+ |
|                                                                    |
|  +------------------+  +------------------+  +-----------------+ |
|  |  Skill 元数据    |  |  Cron 调度器     |  |  会话与认证     | |
|  |  与工具注册表    |  |  (5秒轮询)       |  |  管理           | |
|  +------------------+  +------------------+  +-----------------+ |
|                                                                    |
|  +------------------+  +------------------+  +-----------------+ |
|  |   Telegram       |  |  SQLite 存储     |  |  OS 密钥链      | |
|  |   集成           |  |  (rusqlite)      |  |  集成           | |
|  +------------------+  +------------------+  +-----------------+ |
+------------------------------------------------------------------+

3.2 技术栈

层级 技术
前端 React + Redux Toolkit + Vite
桌面壳 Tauri v2 + CEF（Chromium Embedded Framework）
核心引擎 Rust + Tokio 异步运行时
通信 JSON-RPC 2.0 + WebSocket + Tauri IPC
数据库 SQLite (rusqlite) + FTS5 全文搜索
内存加密 AES-256-GCM + Argon2id 密钥派生
网络 rustls TLS（不依赖 OpenSSL）
AI 协议 MCP（Model Context Protocol）
技能运行时 Node.js (v22.11.0 managed) + Rust 原生处理
搜索 混合搜索（70% 向量相似 + 30% FTS5 全文）
嵌入模型 OpenAI text-embedding-3-small
知识图谱 Neo4j REST API

3.3 仓库结构（Monorepo）

openhuman/
├── app/                    # React 应用，Tauri 壳，Vitest 测试
│   ├── src/               # 前端源码
│   ├── src-tauri/         # Tauri 配置和 vendored 依赖
│   └── test/              # 前端测试
├── src/                   # Rust 核心库 + openhuman-core 二进制
├── docs/                  # 内部文档
├── gitbooks/              # GitBook 文档
│   └── developing/        # 架构、设置、测试指南
├── scripts/               # 开发、测试、调试脚本
├── packages/              # 各平台安装包（AUR 等）
├── Dockerfile             # 核心 Docker 镜像
├── docker-compose.yml     # 自托管 Compose
├── Cargo.toml             # Rust 工作区配置
├── package.json           # pnpm 工作区配置
├── .env.example           # 环境变量模板
├── CONTRIBUTING.md        # 贡献指南
├── AGENTS.md              # AI Agent 仓库规则
└── CLAUDE.md              # 额外贡献者指南

3.4 性能指标

指标 OpenHuman (Tauri + Rust) 典型 Electron 应用
二进制大小 CEF 运行时主导 ~150 MB+
冷启动 < 500ms 2-5 秒
GC 停顿 无（Rust 所有权模型） V8 GC 停顿
内存安全 编译期保证 运行时异常

4. 安装指南

4.1 系统要求

平台 要求
macOS x64 / ARM64，macOS 11+
Windows x64 / ARM64，Windows 10+
Linux x64 / ARM64（Debian/Ubuntu/Arch 等）

4.2 方法一：包管理器安装（推荐）

macOS（Homebrew tap）：

brew tap tinyhumansai/core
brew install openhuman

Linux（Debian/Ubuntu — 签名 apt 源）：

sudo apt-get install -y --no-install-recommends gnupg2 curl ca-certificates

# 添加签名密钥
curl -fsSL https://tinyhumansai.github.io/openhuman/apt/KEY.gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/openhuman.gpg

# 添加 apt 源
echo "deb [signed-by=/etc/apt/keyrings/openhuman.gpg arch=amd64] \
  https://tinyhumansai.github.io/openhuman/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/openhuman.list

# 安装
sudo apt-get update
sudo apt-get install -y openhuman

Linux（Arch Linux — AUR）：

# 使用 AUR helper
yay -S openhuman-bin

# 或手动构建
cd packages/arch/openhuman-bin
makepkg --syncdeps --install

Windows：

从 GitHub Releases 页面 下载签名的 .msi 文件并运行。

4.3 方法二：脚本安装

注意： 脚本安装方式无法验证完整性，优先使用包管理器安装。

macOS / Linux：

# 直接安装
curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash

# 预览安装（不实际安装）
curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash -s -- --dry-run

Windows（PowerShell）：

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

4.4 方法三：手动安装

从 GitHub Releases 下载对应平台的安装文件：

  • macOS: .dmg
  • Windows: .msi
  • Linux: .deb / .AppImage

4.5 方法四：安装 headless core（无图形界面）

仅安装 Rust 核心（适合服务器/远程部署）：

# 自动选择架构
ARCH="$(uname -m)"
case "$ARCH" in
  x86_64)  TARGET=x86_64-unknown-linux-gnu  ;;
  aarch64) TARGET=aarch64-unknown-linux-gnu ;;
  *) echo "Unsupported arch: $ARCH"; exit 1 ;;
esac

VERSION=0.57.11
curl -fsSL "https://github.com/tinyhumansai/openhuman/releases/download/v${VERSION}/openhuman-core-${VERSION}-${TARGET}.tar.gz" \
  | tar -xz -C /usr/local/bin

openhuman-core --version

4.6 方法五：Docker 安装

使用官方镜像：

# 拉取最新镜像
docker pull ghcr.io/tinyhumansai/openhuman-core:latest

# 拉取指定版本
docker pull ghcr.io/tinyhumansai/openhuman-core:v0.57.11

# 运行
docker run -d --name openhuman-core -p 7788:7788 \
  -e OPENHUMAN_CORE_TOKEN="$(openssl rand -hex 32)" \
  -e BACKEND_URL=https://api.tinyhumans.ai \
  -e OPENHUMAN_APP_ENV=production \
  -v openhuman-workspace:/home/openhuman/.openhuman \
  ghcr.io/tinyhumansai/openhuman-core:latest

使用 Docker Compose：

git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

# 配置环境变量
cp .env.example .env
# 编辑 .env，至少设置：
#   BACKEND_URL=https://api.tinyhumans.ai
#   OPENHUMAN_CORE_TOKEN=$(openssl rand -hex 32)
#   OPENHUMAN_APP_ENV=production

# 构建并启动
docker compose up -d

# 验证
curl -fsS http://localhost:7788/health

4.7 方法六：从源码编译

前置条件：

工具 版本要求 说明
Git 最新稳定版 克隆和更新 vendored 子模块
Node.js >= 24.0.0 安装 Node 24 或更高
pnpm 10.10.0 由 package.json 强制指定
Rust 1.93.0 通过 rustup 安装，含 rustfmt 和 clippy
CMake 最新稳定版 Whisper 绑定等原生依赖需要
Ninja 最新稳定版 macOS 上 CEF helper 构建需要
ripgrep 最新稳定版 预推送 lint 检查需要

macOS 快速安装：

brew install node@24 pnpm rustup-init cmake ninja ripgrep

rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0
rustup target add x86_64-apple-darwin  # Apple Silicon 也需要

# 代码签名证书（一次性）
bash scripts/setup-dev-codesign.sh

Arch Linux 快速安装：

sudo pacman -S --needed nodejs npm rustup cmake base-devel clang openssl \
  alsa-lib xdotool libxtst libxi libevdev gtk3 webkit2gtk-4.1 \
  libayatana-appindicator librsvg patchelf nss nspr at-spi2-core \
  libcups libdrm libxkbcommon libxcomposite libxdamage libxfixes \
  libxrandr mesa pango cairo libxshmfence

npm install -g pnpm@10.10.0
rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0

Windows 额外安装：

1. Visual Studio C++ Build Tools (MSVC v143, ~5.4 GB)
2. LLVM / Clang (~822 MB) - 设置 LIBCLANG_PATH 环境变量
3. CMake - winget install Kitware.CMake

编译步骤：

# 1. 克隆仓库
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

# 2. 获取 vendored Tauri/CEF 源码（必需）
git submodule update --init --recursive

# 3. 安装 JS 依赖
pnpm install

# 4. 构建桌面应用
pnpm build

5. 使用方法（全面详解）

5.1 首次启动与引导

步骤 1：启动应用

# 桌面应用
openhuman      # 命令行启动
# 或从应用菜单/桌面快捷方式启动

步骤 2：注册/登录

  • 首次启动会打开欢迎界面
  • 使用 OpenHuman 托管服务进行账户登录
  • 也可选择自定义/本地设置

步骤 3：连接数据源

  • 通过一键 OAuth 连接 Gmail、Notion、GitHub、Slack 等服务
  • 每个连接自动暴露为类型化工具
  • 自动拉取（每 20 分钟）开始将新数据拉入记忆树

步骤 4：配置 AI 运行方式

  • 默认模式： 使用 OpenHuman 托管后端进行模型路由（一个订阅包含所有模型）
  • 自定义模式： 自带模型 API Key（OpenAI、Anthropic 等）
  • 本地模式： 通过 Ollama 或 LM Studio 运行本地模型

5.2 日常使用 — 与 Agent 对话

基本交互：

  • 在桌面应用的聊天界面输入自然语言指令
  • Agent 会自动选择最适合的工具和模型
  • 支持多轮对话，记忆树提供完整上下文

常见使用场景：

"总结一下我最近的 Gmail 邮件"
"帮我查看 GitHub 上未解决的 PR"
"整理本周的日历安排"
"搜索并总结最近的 AI 新闻"
"帮我写一封回复邮件"
"分析我的 Slack 消息模式"

5.3 记忆树操作

查看记忆树：

# 记忆数据存储在 ~/.openhuman/ 目录下
ls ~/.openhuman/

# 使用 Obsidian 打开记忆仓库
# （记忆以 .md 文件格式存储，兼容 Obsidian）

记忆树层级结构：

~/.openhuman/
├── memory.db              # SQLite 记忆数据库
├── obsidian-vault/        # Obsidian 风格 Wiki
│   ├── gmail/             # Gmail 来源的记忆
│   │   ├── 2026-06/
│   │   │   ├── daily-summary.md
│   │   │   └── topics/
│   ├── github/            # GitHub 来源的记忆
│   ├── slack/             # Slack 来源的记忆
│   └── personal/          # 个人笔记
├── config.toml            # 配置文件
└── core.token             # Core 认证令牌

手动编辑记忆：

  • 记忆以 Markdown 文件形式存储
  • 可直接用文本编辑器或 Obsidian 编辑
  • 编辑后的文件会在下次同步时被重新纳入

配置记忆后端：

# 在 config.toml 中
[ memory ]
backend = "agentmemory"    # 使用 agentmemory 后端

5.4 第三方集成管理

连接新服务：

  1. 打开桌面应用设置
  2. 找到"Integrations"页面
  3. 点击你想连接的服务
  4. 完成 OAuth 授权流程
  5. 服务工具自动注册到 Agent 可用工具集

管理的集成列表（部分）：

类别 服务数量 示例
生产力 30+ Gmail, Calendar, Drive, Docs, Sheets
开发 20+ GitHub, GitLab, VS Code
协作 15+ Slack, Notion, Linear, Jira
消息 10+ Telegram, Discord, WhatsApp
支付 5+ Stripe
其他 30+ 各类 API

Composio 直连模式（高级）：

如果你有自己的 Composio API Key，可以配置直连模式：

# 在 .env 中设置
COMPOSIO_API_KEY=your_own_key

注意：直连模式下，实时触发器 webhook 需要自行托管和接入。

5.5 模型路由配置

默认模式（推荐）：

  • OpenHuman 自动选择最适合的模型
  • 推理型任务使用推理能力强的模型
  • 快速回复使用轻量模型
  • 视觉任务使用视觉模型
  • 一个订阅覆盖所有模型

自定义模式：

# 在 app/.env.local 中
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx

本地 AI（Ollama）：

# 启动 Ollama
ollama serve

# 拉取模型
ollama pull llama3

# 在 OpenHuman 中配置本地 AI
# 桌面应用设置 → AI → Local AI → 启用 Ollama
# 或通过环境变量：
OLLAMA_HOST=http://127.0.0.1:11434

本地 AI（LM Studio）：

# 启动 LM Studio
# 桌面应用设置 → AI → Local AI → 启用 LM Studio
# 或通过环境变量：
LM_STUDIO_HOST=http://127.0.0.1:1234

5.6 桌面吉祥物

功能：

  • 桌面常驻吉祥物，会说话、会动
  • 感知周围环境（摄像头）
  • 加入 Google Meet 作为真实参与者
  • 口型同步（TTS 输出）
  • 在你停止输入后仍在后台思考

配置：

  • 桌面应用设置 → Mascot
  • 选择外观、语音、行为模式

5.7 语音交互

语音输入（STT）：

  • 点击麦克风按钮开始语音输入
  • 自动转换为文本发送给 Agent

语音输出（TTS）：

  • 默认使用 ElevenLabs TTS
  • 支持语音合成选项配置
  • 吉祥物口型同步

实时语音对话：

  • 支持与 Agent 进行连续的语音对话
  • 吉祥物显示口型动画

5.8 内置工具使用

网络搜索：

Agent 自动在对话中使用，无需手动配置
例如："搜索最新的 AI 研究论文"

网页抓取：

Agent 可以抓取指定网页内容并分析
例如："总结一下 https://example.com 的内容"

文件系统操作：

Agent 可以读写本地文件
例如："帮我整理 ~/Documents 下的文件"

Git 操作：

Agent 可以执行 Git 命令
例如："创建一个新的 Git 分支"
"帮我提交最近的修改"

代码工具：

- Lint 检查
- 运行测试
- 代码搜索（Grep）
- 文件读写

定时任务（Cron）：

Agent 支持调度定时任务
内部使用 5 秒轮询的 Cron 调度器
支持标准 Cron 表达式

5.9 Google Meet 智能体

加入会议：

  1. 在 Agent 对话中请求加入 Google Meet
  2. 提供会议链接或邀请码
  3. Agent 作为真实参与者加入
  4. 可以监听会议内容、回答问题的摘要

会议期间：

  • 吉祥物在桌面显示会议状态
  • Agent 实时处理会议音频
  • 可以生成会议记录

5.10 Obsidian Wiki 使用

打开 Wiki：

# 使用 Obsidian 打开记忆仓库
obsidian ~/.openhuman/obsidian-vault/
# 或手动在 Obsidian 中选择该目录

Wiki 内容结构：

  • 按数据源分类（gmail/、github/、slack/等）
  • 按日期组织每日摘要
  • 按主题分组相关记忆
  • 支持双向链接（Obsidian 原生功能）

自定义 Wiki：

  • 添加个人笔记
  • 创建主题分类
  • 使用 Obsidian 插件增强功能

5.11 消息渠道

支持的渠道：

  • Telegram
  • Discord
  • 其他（通过集成）

配置消息渠道：

  1. 在桌面应用设置中找到"Messaging"
  2. 选择要启用的渠道
  3. 完成 OAuth/Bot Token 配置
  4. 通过该渠道与 Agent 对话

5.12 远程核心连接

将桌面客户端指向远程核心：

# 在 app/.env.local 中设置
OPENHUMAN_CORE_RUN_MODE=external
OPENHUMAN_CORE_RPC_URL=https://core.example.com/rpc
OPENHUMAN_CORE_TOKEN=你的令牌

首次运行时：

  1. 打开桌面应用
  2. 选择"Remote/External Core"模式
  3. 输入远程核心的 RPC URL
  4. 输入 Bearer Token
  5. 点击"Test connection"测试连接
  6. 连接成功后开始使用

6. 配置说明

6.1 配置文件位置

路径 说明
~/.openhuman/ 默认工作区（Rust 核心 + 本地应用数据）
~/.openhuman-staging/ 测试环境工作区
~/.openhuman/config.toml 核心配置文件
~/.openhuman/core.token Core 认证令牌
app/.env.local 前端环境变量（不提交）
.env Rust 核心 + Tauri 环境变量

6.2 环境变量（核心）

变量 默认值 说明
OPENHUMAN_APP_ENV production 应用环境（production/staging）
BACKEND_URL https://api.tinyhumans.ai 后端 API 地址
OPENHUMAN_CORE_PORT 7788 Core RPC 端口
OPENHUMAN_CORE_RPC_URL http://127.0.0.1:7788/rpc Core RPC 地址
OPENHUMAN_CORE_TOKEN （自动生成） RPC Bearer Token
OPENHUMAN_CORE_HOST 127.0.0.1 Core 绑定地址（Docker 用 0.0.0.0）
OPENHUMAN_CORE_ALLOWED_ORIGINS - 允许的 CORS 源
OPENHUMAN_CORE_RUN_MODE local 运行模式（local/external）
RUST_LOG info 日志级别
OLLAMA_HOST http://127.0.0.1:11434 Ollama 地址
LM_STUDIO_HOST http://127.0.0.1:1234 LM Studio 地址
SKILLS_REGISTRY_URL - Skills 注册表 URL
SKILLS_LOCAL_DIR - 本地 Skills 目录
COMPOSIO_API_KEY - Composio API 密钥

6.3 config.toml 示例

[general]
app_env = "production"
backend_url = "https://api.tinyhumans.ai"

[core]
port = 7788
rpc_url = "http://127.0.0.1:7788/rpc"
run_mode = "local"  # local | external

[memory]
backend = "sqlite"  # sqlite | agentmemory

[model_routing]
mode = "managed"  # managed | custom | local

[update]
restart_strategy = "self_replace"  # self_replace | supervisor
rpc_mutations_enabled = true

[local_ai]
ollama_host = "http://127.0.0.1:11434"
lm_studio_host = "http://127.0.0.1:1234"

6.4 环境变量模板

项目提供了两个环境变量模板：

  • .env.example — Rust 核心、Tauri 壳、共享运行时设置
  • app/.env.example — 前端 VITE_* 变量
# 复制到本地文件
cp .env.example .env
cp app/.env.example app/.env.local

7. 云端部署

7.1 部署场景

  • 多设备访问： 多台桌面客户端指向同一托管核心
  • 内部测试： 无需本地 Rust 工具链
  • 长期任务： Cron 任务和 webhook 在笔记本休眠后仍运行

7.2 部署路径

路径 1：DigitalOcean App Platform（一键部署）

  1. 点击 “Deploy to DO” 按钮
  2. 在 App Platform UI 中设置环境变量
  3. 替换 OPENHUMAN_CORE_TOKEN 为强密码
  4. 保存并等待部署完成

路径 2：任意 VPS + Docker Compose

# 服务器端
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

cp .env.example .env
# 编辑 .env：
#   BACKEND_URL=https://api.tinyhumans.ai
#   OPENHUMAN_CORE_TOKEN=$(openssl rand -hex 32)
#   OPENHUMAN_APP_ENV=production

docker compose up -d

# 验证
curl -fsS http://localhost:7788/health

路径 3：Fly.io

仓库包含 .fly/ 目录，支持 Fly.io 部署。

路径 4：systemd 守护进程（无 Docker）

# 安装 headless core（见 4.5 节）
# 创建 systemd 服务
sudo tee /etc/systemd/system/openhuman.service << 'EOF'
[Unit]
Description=OpenHuman Core
After=network.target

[Service]
ExecStart=/usr/local/bin/openhuman-core serve
Environment=OPENHUMAN_CORE_TOKEN=your_token
Environment=BACKEND_URL=https://api.tinyhumans.ai
Restart=always
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now openhuman

7.3 端点说明

端点 方法 说明
/health GET 健康检查（公开）
/rpc POST JSON-RPC 入口（Bearer Token 保护）
/events GET 事件流（公开）
/ws/dictation GET 语音识别流（公开）

7.4 TLS 配置

# Caddyfile 示例
core.example.com {
  reverse_proxy localhost:7788
}

7.5 Token 轮换

# 1. 生成新 Token
openssl rand -hex 32 > /tmp/new-token

# 2. 更新 .env
sed -i.bak "s|^OPENHUMAN_CORE_TOKEN=.*|OPENHUMAN_CORE_TOKEN=$(cat /tmp/new-token)|" .env
rm /tmp/new-token .env.bak

# 3. 重启
docker compose up -d --force-recreate openhuman-core

# 4. 更新所有桌面客户端的 Token

7.6 自动更新

# 检查更新
openhuman-core update-check

# 应用更新
openhuman-core update-apply

# 运行更新（含重启）
openhuman-core update-run

8. 开发指南

8.1 开发模式

# 仅前端开发（Vite 开发服务器）
pnpm dev

# 桌面应用开发（含 Tauri + CEF）
pnpm --filter openhuman-app dev:app

# Rust 核心独立运行
cargo run --manifest-path Cargo.toml --bin openhuman-core

# Web 开发 + 远程核心
OPENHUMAN_CORE_RPC_URL=http://127.0.0.1:7788/rpc pnpm dev

8.2 验证命令

# 前端类型检查
pnpm typecheck

# 前端 Lint
pnpm lint

# 格式化检查
pnpm format:check

# Rust 检查
cargo check --manifest-path Cargo.toml
cargo check --manifest-path app/src-tauri/Cargo.toml

8.3 测试命令

# 前端单元测试
pnpm test

# 带覆盖率的测试
pnpm test:coverage

# Rust 测试
pnpm test:rust

# 桌面 E2E 测试
pnpm test:e2e

# 调试运行（前端）
pnpm debug unit ...

# 调试运行（Rust）
pnpm debug rust ...

8.4 Skills 开发

Skills 在独立仓库 tinyhumansai/openhuman-skills 中开发。

Skill 结构：

skill-name/
├── SKILL.md              # Skill 元数据和指令
├── references/           # 参考文件
├── templates/            # 模板文件
├── scripts/              # 脚本文件
└── assets/               # 资源文件

指向本地 Skills：

# 在 .env 中设置
SKILLS_LOCAL_DIR=/path/to/your/local/skills

8.5 分支与 PR

# 开始分支
git fetch upstream
git checkout main
git pull --ff-only upstream main
git checkout -b feat/your-feature

# 推送并提交 PR
git push origin feat/your-feature
# 在 GitHub 上打开 PR 到 tinyhumansai/openhuman:main

9. 对比分析

特性 Claude Cowork OpenClaw Hermes Agent OpenHuman
开源 闭源 MIT MIT GNU GPL3
易用性 桌面 + CLI 终端优先 终端优先 UI 优先，几分钟上手
成本 订阅 + 附加 自带模型 自带模型 单一订阅 + TokenJuice
记忆 对话范围 依赖插件 自学习 记忆树 + Obsidian 仓库
集成 少量连接器 自行接入 自行接入 118+ 通过 OAuth
自动拉取 无 无 无 每 20 分钟同步
API 碎片化 需多个 Key 自带 Key 多供应商 一个账户
模型路由 单一模型 手动 手动 内置自动路由
原生工具 仅代码 仅代码 仅代码 代码 + 搜索 + 抓取 + 语音

10. 安全与隐私

10.1 安全架构

安全层 实现
凭据存储 OS 密钥链（macOS Keychain, Windows Credential Manager, Linux Secret Service）
记忆加密 AES-256-GCM + Argon2id 密钥派生
工具沙箱 SecurityPolicy + Docker/Bubblewrap/Firejail/Landlock
认证 一次性登录 Token（5 分钟 TTL）
网络 rustls TLS（不依赖 OpenSSL）
状态管理 敏感数据仅存 Redux 内存和 OS 密钥链
注入防护 Prompt injection guard（服务端 allow/review/block）

10.2 数据隐私

  • 本地优先： 记忆树、Obsidian 仓库、工作区配置全部存储在本机
  • 本地加密： AI 记忆使用 AES-256-GCM 加密，Argon2id 派生密钥
  • 数据归属： 工作流数据保留在设备上，属于用户
  • 托管服务选择： 可选择完全本地模式，避免使用托管后端

11. 注意事项与已知问题

11.1 当前状态

  • 活跃开发中： 每周多次提交，可能存在不完善之处

11.2 已知问题

Linux AppImage：

  • Wayland 下可能崩溃（见 #2463）
  • Arch 用户可能遇到 sharun: Interpreter not found!
  • 建议使用 .deb 包而非 AppImage

macOS 开发：

  • CEF 缓存锁定：开发和发布版本不能同时运行
  • 解决方法：pkill -f "OpenHuman.app/Contents" && pkill -f "openhuman-core"

Windows：

  • WSL + 经典 X11 转发不受支持（可能导致挂起或崩溃）
  • 建议使用原生 Windows 开发或 Windows 11 WSLg

Docker：

  • App Platform Basic 不提供块存储，重新部署会丢失工作区数据
  • 建议使用持久卷或 Docker Compose 方案

11.3 不支持的平台

  • Android
  • iOS
  • 独立 Web 客户端（目前有实验性目标，但不作为产品发布）

11.4 托管服务依赖

  • 默认体验使用 OpenHuman 托管服务（账户登录、模型路由、搜索代理、Composio 连接器）
  • 部分实时触发器和托管功能仍需托管后端
  • 可选择自定义/本地设置减少托管依赖

附录：相关链接

资源 链接
GitHub 仓库 https://github.com/tinyhumansai/openhuman
Skills 仓库 https://github.com/tinyhumansai/openhuman-skills
官方文档 https://tinyhumans.gitbook.io/openhuman/
官方网站 https://tinyhumans.ai/openhuman
下载页面 https://tinyhumans.ai/openhuman
GitHub Releases https://github.com/tinyhumansai/openhuman/releases
贡献指南 https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md
Discord https://discord.tinyhumans.ai/
Reddit https://www.reddit.com/r/tinyhumansai/
X/Twitter https://x.com/tinyhumansai
作者 https://x.com/senamakel
Product Hunt https://www.producthunt.com/products/openhuman
架构文档 https://tinyhumans.gitbook.io/openhuman/developing/architecture
agentmemory https://github.com/rohitg00/agentmemory
# 人工智能 # 人机交互 # 低代码
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

告别多接口对接烦恼：AI聚合平台统一调用方案详解

avatar AtomGit开源社区

AI文章解读（四）-2026年企业如何构建AI智能体

AI 在企业的竞争,已经从"模型能力竞争"切换到"上下文密度竞争"

avatar AtomGit开源社区
cover

AI教材编写新选择！低查重AI工具，快速生成规范教材内容！

avatar AtomGit开源社区