开始设置

如何从源码构建 OpenHuman——工具链、捆绑的 Tauri CLI，以及本地桌面构建。

本指南涵盖完整的桌面/源码安装路径和发行版安装程序。

如果你在一台新机器上只需要仓库根目录的 Rust crate，请使用 构建 Rust 核心。该页面记录了固定的 Rust 工具链、操作系统软件包前置条件，以及精确的 cargo 命令，用于 openhuman-core.

本指南涵盖两条路径：

1. 从源码构建并编译 OpenHuman

2. 安装最新稳定版二进制文件

前提条件

• git

• Node.js 24 或更新版本（参见 app/package.json)

• pnpm@10.10.0 （参见根目录的 package.json packageManager 字段）

• Rust 1.93.0 及以上，直到 rustup 配合 rustfmt 以及 clippy 来合成（见 rust-toolchain.toml)

• CMake，原生 Rust 依赖所必需

• 位于 app/src-tauri/vendor/下的 Git 子模块，供内置的、支持 CEF 的 Tauri CLI 使用

• 平台桌面构建工具：macOS 上的 Xcode 命令行工具，或 Linux 上的 Tauri GTK/WebKit/AppIndicator 软件包集合

macOS Homebrew 快速开始：

brew install node@24 pnpm rustup-init cmake
rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0

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

从源码构建（本地编译）

在仓库根目录下运行：

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

# 2) 获取内置的 Tauri/CEF 源码
git submodule update --init --recursive

# 3) 安装 JS 依赖（工作区）
pnpm install

# 4) 构建桌面应用产物
pnpm build

如果进行本地开发而不是生产构建：

# 仅 Web UI 开发
pnpm dev

# 使用内置的 Tauri/CEF CLI 进行桌面应用开发：从工作区根目录运行
pnpm --filter openhuman-app dev:app

安装最新稳定版（macOS/Linux x64）

主要安装命令：

curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash

安装程序行为：

• 为你的平台解析最新的稳定版 OpenHuman 发行版

• 在可用时验证制品摘要

• 在本地安装（默认不使用 sudo）

• macOS：安装 OpenHuman.app 到 到 ~/Applications

• Linux x64：将 AppImage 安装为 ~/.local/bin/openhuman 并写入桌面条目

Arch Linux 软件包配方

该仓库包含一个 openhuman-bin AUR 配方，位于 packages/arch/openhuman-bin。它使用官方 x86_64 AppImage 作为二进制来源，在 makepkg期间解压捆绑的应用目录，安装桌面条目，并提供 /usr/bin/openhuman.

在该软件包发布到 AUR 之前，请先在 Arch 上本地构建：

cd packages/arch/openhuman-bin
makepkg --syncdeps --install

发布之后，Arch 用户可以使用以下命令安装：

yay -S openhuman-bin

有用的标志：

# 预览操作而不写入文件
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

Windows 安装程序行为：

• 解析最新稳定版

• 下载 x64 的 MSI/EXE

• 在可用时验证摘要

• 在安装程序包支持的情况下执行按用户安装

ARM Linux 构建（aarch64）

由于 CEF 和 GTK 依赖，ARM Linux 构建需要特殊处理。

前提条件

# 为无头构建/测试安装 xvfb
sudo apt install xvfb

构建

cd app
pnpm tauri build --target aarch64-unknown-linux-gnu

运行 ARM 二进制文件

该二进制文件需要设置 CEF 库路径：

选项 1 - 直接调用

REL_DIR=app/src-tauri/target/aarch64-unknown-linux-gnu/release
CEF_DIR=$(ls -d "$REL_DIR"/build/cef-dll-sys-*/out/cef_linux_aarch64 2>/dev/null | head -n1)
export LD_LIBRARY_PATH="$CEF_DIR:$REL_DIR/deps:$REL_DIR${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
"$REL_DIR/OpenHuman" --no-sandbox

选项 2 - 包装脚本（推荐）

保存到 ~/bin/openhuman 并使其可执行（chmod +x ~/bin/openhuman):

#!/bin/bash
REL_DIR=/path/to/app/src-tauri/target/aarch64-unknown-linux-gnu/release
CEF_DIR=$(ls -d "$REL_DIR"/build/cef-dll-sys-*/out/cef_linux_aarch64 2>/dev/null | head -n1)
export LD_LIBRARY_PATH="$CEF_DIR:$REL_DIR/deps:$REL_DIR${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
exec "$REL_DIR/OpenHuman" --no-sandbox "$@"

DEB 软件包安装

DEB_FILE=$(ls app/src-tauri/target/aarch64-unknown-linux-gnu/release/bundle/deb/OpenHuman_*_arm64.deb | head -n1)
sudo dpkg -i "$DEB_FILE"

GTK 初始化修复

ARM 构建要求在 Tauri 创建系统托盘之前先初始化 GTK。此处理已在 vendor/tauri-cef/crates/tauri-runtime-cef/src/lib.rs:

// 在 CEF 初始化后，添加：
#[cfg(target_os = "linux")]
{
    gtk::init().ok();
}

如果托盘因“GTK has not been initialized”而初始化失败，请在确保此修复到位后重新构建。

手动下载链接（所有平台）：

• 网站：https://tinyhuman.ai/openhuman

• 最新发行版：https://github.com/tinyhumansai/openhuman/releases/latest

故障排查

macOS： pnpm dev:app 以“CEF cache is held by another OpenHuman instance”退出

症状

pnpm dev:app （或任何 Tauri shell 的调试构建）会在窗口出现之前退出，并显示类似如下的信息：

[openhuman] 位于 /Users/<you>/Library/Caches/com.openhuman.app/cef 的 CEF 缓存正被另一个 OpenHuman 实例（主机 <hostname>，pid 12345）占用。
退出正在运行的实例后重试。
解决方法：
  pkill -f "OpenHuman.app/Contents"
  pkill -f "openhuman-core"

原因

CEF（Chromium Embedded Framework）通过位于 SingletonLock 下的符号链接对其用户数据目录持有独占锁 ~/Library/Caches/com.openhuman.app/cef。已安装的 .app bundle 和开发二进制文件使用相同的标识符（com.openhuman.app），因此不能并行运行。如果没有预检， cef::initialize 会返回失败，而内置的 tauri-runtime-cef 会触发 Rust 回溯并且没有可操作的错误信息（这是预检落地之前的 issue #864）。

修复方法

退出另一个 OpenHuman 实例并重新运行。最快路径：

pkill -f "OpenHuman.app/Contents"
pkill -f "openhuman-core"
pnpm dev:app

如果锁是由崩溃进程留下的（PID 已不存在），预检会自动移除过期的 SingletonLock 锁，因此开发启动会继续进行，无需手动清理。

已知限制

开发版和发行版构建仍然共用 com.openhuman.app 作为缓存标识符。将开发版隔离到单独的 com.openhuman.app.dev 缓存需要修改内置的 tauri-runtime-cef （缓存路径在运行时由 bundle 标识符在内部构建，而不是暴露给 openhuman shell）。作为 #864 的后续事项跟踪。

陈旧的 openhuman 核心端口上的 RPC 进程

症状

之前的 Tauri 构建或 openhuman-core 运行 测试框架留下了一个进程在监听 OPENHUMAN_CORE_PORT （默认 7788。在 issue #1130 之前，新的 Tauri 构建会静默附加到该监听器，导致版本漂移，以及当新构建的 OPENHUMAN_CORE_TOKEN 不匹配时出现 401。

当前行为（issue #1130）

core_process::ensure_running 现在会在启动时探测该端口：

• 如果 GET / 将该监听器识别为 OpenHuman 核心（JSON 响应体包含 "name": "openhuman"），则会将其视为来自上一次运行的残留进程并主动终止（SIGTERM，Unix 上随后 SIGKILL 750 毫秒后； taskkill /F /T /PID 在 Windows 上）。随后 Tauri 主机启动自己的新嵌入式核心。

• 如果监听器是其他东西（或者不说 HTTP），启动会明确失败，并在日志中暴露冲突，而不是静默附加。

• 设置 OPENHUMAN_CORE_REUSE_EXISTING=1 以重新启用旧的“附加到任何东西”行为，这在运行 openhuman-core 运行 作为手动调试测试框架时很有用。

手动清理（仍然有效）

pkill -f "OpenHuman.app/Contents"
pkill -f "openhuman-core"