# 设置

本指南涵盖完整的桌面版/源代码安装路径以及发布安装程序。

如果你只需要在一台全新的机器上使用仓库根目录的 Rust crate，请使用 [构建 Rust Core](/openhuman/zh/kai-fa/building-rust-core.md)。该页面记录了固定的 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 依赖所必需
* 位于以下路径下的 Git 子模块 `app/src-tauri/vendor/`，这是带有 CEF 感知能力的 vendored Tauri CLI 所必需的
* 平台桌面构建工具：macOS 上的 Xcode Command Line Tools，或 Linux 上的 Tauri GTK/WebKit/AppIndicator 软件包集合

macOS Homebrew 快速开始：

```bash
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 快速开始：

```bash
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
```

## 从源代码构建（本地编译）

在仓库根目录运行：

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

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

# 3) 安装 JS 依赖（workspace）
pnpm install

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

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

```bash
# 仅 Web UI 开发
pnpm dev

# 使用 vendored Tauri/CEF CLI 进行桌面应用开发：从 workspace 根目录运行
pnpm --filter openhuman-app dev:app
```

## 安装最新稳定版发布包（macOS/Linux x64）

主要安装命令：

```bash
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`](https://github.com/tinyhumansai/openhuman/blob/main/packages/arch/openhuman-bin/README.md)。它使用官方 x86\_64 AppImage 作为二进制来源，在 `makepkg`期间提取捆绑的应用目录树，安装桌面条目，并公开 `/usr/bin/openhuman`.

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

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

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

```bash
yay -S openhuman-bin
```

有用的标志：

```bash
# 预览操作而不写入文件
curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash -s -- --dry-run
```

## Windows（最新稳定版）

使用 PowerShell：

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

Windows 安装程序行为：

* 解析最新稳定版发布
* 下载适用于 x64 的 MSI/EXE
* 在可用时验证摘要
* 在安装程序包支持的情况下执行按用户安装

## ARM Linux 构建（aarch64）

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

### 前置要求

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

### 构建

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

### 运行 ARM 二进制文件

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

### 选项 1 - 直接调用

```bash
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`):

```bash
#!/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 软件包安装

```bash
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`:

```rust
// 在 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` 会返回失败，而 vendored 的 `tauri-runtime-cef` 会触发 panic，产生 Rust 回溯且没有可操作的信息（在加入预检之前，这是问题 #864）。

**修复**

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

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

如果锁是由已崩溃的进程遗留下来的（PID 已不再存活），预检会自动移除过期的 `SingletonLock` ，然后开发启动会继续，无需手动清理。

**已知限制**

开发版和发布版构建仍然共享 `com.openhuman.app` 作为缓存标识符。将开发环境隔离到单独的 `com.openhuman.app.dev` 缓存需要修改 vendored 的 `tauri-runtime-cef` （缓存路径是在运行时根据 bundle 标识符构建的，并未暴露给 openhuman shell）。作为 #864 的后续事项进行跟踪。

### 陈旧的 `openhuman` 位于 core 端口上的 RPC 进程

**症状**

先前的 Tauri 构建或 `openhuman-core 运行` 测试支架遗留了一个进程，在 `OPENHUMAN_CORE_PORT` （默认值 `7788`）上监听。在问题 #1130 之前，新的 Tauri 构建会静默附加到该监听器，导致版本漂移，并在新构建的 `OPENHUMAN_CORE_TOKEN` 不匹配时出现 401。

**当前行为（问题 #1130）**

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

* 如果 `GET /` 将该监听器识别为 OpenHuman core（JSON 主体包含 `"name": "openhuman"`），则它会被视为来自先前运行的陈旧进程，并被主动终止（`SIGTERM`，然后 `SIGKILL` 在 Unix 上 750ms 后； `taskkill /F /T /PID` 在 Windows 上）。随后 Tauri 主机会生成它自己的全新嵌入式 core。
* 如果监听器是其他东西（或不讲 HTTP），启动将以明显方式失败，并在日志中显示冲突，而不是静默附加。
* 设置 `OPENHUMAN_CORE_REUSE_EXISTING=1` 以重新选择旧版的附加到任意对象行为，这在将 `openhuman-core 运行` 作为手动调试支架运行时很有用。

**手动清理（仍然有效）**

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/getting-set-up.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.