> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/getting-set-up.md).

# 开始设置

从源代码构建 OpenHuman，或安装一个发布版：工具链、子模块、桌面构建以及各平台安装程序。

让 OpenHuman 运行起来有两种方式：从源码构建，或安装最新发布版。本页涵盖这两种方式。

如果你只需要位于 `crates/` 下的 Rust 工作区（没有 Node，没有 Tauri），请使用 [构建 Rust 核心](/openhuman/zh/kai-fa/building-rust-core.md)。它包含固定的工具链、操作系统软件包以及 `cargo` 用于 `openhuman-core`.

## 先决条件

* `git`
* Node.js 24 或更高版本（参见 `app/package.json`)
* `pnpm@10.10.0` （参见根目录下的 `package.json` `packageManager` 字段）
* Rust 1.99.1 到 `rustup` 使用 `rustfmt` 和 `clippy` （参见 `rust-toolchain.toml`)
* CMake，原生 Rust 依赖所需
* 列出的每个 `vendor/` 子模块 `.gitmodules`，递归初始化（`git submodule update --init --recursive`）。根 `Cargo.toml` `[patch]` 表指向该树，因此 cargo 会读取每个清单文件，不管是否为可选 crate。部分检出总是无法构建
* 平台桌面构建工具：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.99.1 --profile minimal
rustup component add rustfmt clippy --toolchain 1.99.1
```

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.99.1 --profile minimal
rustup component add rustfmt clippy --toolchain 1.99.1
```

## 从源码构建

在仓库根目录运行：

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

# 2) 拉取 vendored tiny* 子模块
git submodule update --init --recursive

# 3) 安装 JS 依赖
pnpm install

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

若要用于开发而不是生产构建：

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

# 桌面应用开发：运行 scripts/run-dev-macos.sh（带开发配置覆盖的 `cargo tauri dev`）
pnpm dev:app

# 其他 Tauri CLI 命令（来自 app/node_modules）针对 crates/openhuman-app/ 运行
pnpm tauri build
```

## 在 macOS 和 Linux 上安装最新发布版

运行安装脚本：

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

该脚本：

* 查找适用于你平台的最新稳定版。
* 使用 SHA-256 摘要校验下载文件。
* 无需 sudo 即可安装。
* 在 macOS 上，安装 `OpenHuman.app` 到 `到 ~/Applications`.
* 在 Linux x64 上，将 AppImage 安装为 `~/.local/bin/openhuman` 并写入桌面项。

若要在不写入文件的情况下预览其行为，请添加 `--dry-run`:

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

### Arch Linux

没有已发布的 AUR 包。仓库中包含一个 `openhuman-bin` 配方，位于 [`packages/arch/openhuman-bin`](https://github.com/tinyhumansai/openhuman/tree/main/packages/arch/openhuman-bin/README.md)。它使用官方 x86\_64 AppImage，在 `makepkg`期间解压，安装桌面项并提供 `/usr/bin/openhuman`。在本地构建：

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

## Windows

使用 PowerShell：

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

该脚本：

* 查找最新稳定版。
* 下载 x64 MSI 或 EXE。
* 检查其 SHA-256 摘要。
* 在安装程序支持的情况下执行按用户安装。

## ARM Linux 构建（aarch64）

CI 构建 `aarch64-unknown-linux-gnu` 目标，在一个 `ubuntu-24.04-arm` 运行器上使用与 x64 相同的 Tauri 命令（参见 [`.github/workflows/build-desktop.yml`](https://github.com/tinyhumansai/openhuman/blob/main/.github/workflows/build-desktop.yml)）。在本地，安装了 Linux 桌面软件包集合后：

```bash
pnpm tauri build --target aarch64-unknown-linux-gnu --bundles deb appimage
```

shell 采用的是标准 Tauri on Wry，因此二进制文件不需要额外的库路径。安装 `.deb` 包并使用 `dpkg -i`.

你也可以从 [tinyhumans.ai/openhuman](https://tinyhumans.ai/openhuman) 下载任何平台的安装程序，或从 [最新发布版](https://github.com/tinyhumansai/openhuman/releases/latest).

## 故障排除

### 核心端口上的 `openhuman` 残留进程

之前的 Tauri 构建或 `openhuman-core 运行` 可能会留下一个进程在 `OPENHUMAN_CORE_PORT` 上监听（默认 `7788`）。如果新的构建连接到它，你会看到版本漂移和 401 错误，因为新构建的 `OPENHUMAN_CORE_TOKEN` 不会匹配。

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

* 如果 `GET /` 将监听者识别为 OpenHuman 核心（一个带有 `"name": "openhuman"`的 JSON 主体），则将其视为残留进程并停止。在 Unix 上会先发送 `SIGTERM`，然后在 `SIGKILL` 750 毫秒后发送。Windows 上则使用 `taskkill /F /T /PID`。随后 Tauri 宿主会启动其内嵌核心。
* 如果监听者是别的东西，或者不支持 HTTP，启动就会失败，日志会显示冲突。
* 设置 `OPENHUMAN_CORE_REUSE_EXISTING=1` 以便改为连接到当前正在监听的进程。当你手动运行 `openhuman-core 运行` 进行调试时，这很有用。

如需手动清理：

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

***

## 另见

* [构建 Rust 核心](/openhuman/zh/kai-fa/building-rust-core.md)：仅 cargo 的路径，不使用 Node 或 Tauri。
* [E2E 测试指南](/openhuman/zh/kai-fa/e2e-testing.md)：本地桌面构建所供给的测试框架。
* [架构](/openhuman/zh/kai-fa/architecture/architecture.md)：shell、核心和前端各自负责什么。
* [云端部署](/openhuman/zh/gong-neng/cloud-deploy.md)：在服务器上以无头方式运行同一个核心。