【VisionFive2 Lite】Hermes Agent 布署

VF2 Lite(CN)
, ,
1

以下是 Hermse Agent 在 VisionFive 2 Lite 开发板上布署的全过程记录。

材料

  1. VisionFive 2 Lite 8G+64G eMMC

  2. Ubuntu 24.04.3 Desktop

  3. Hermse Agent

wx_camera_1775219837792
wx_camera_17752198377921038×584 151 KB

布署

node.js 布署

布署前先要安装 nodejs，由于 node.js 官方没有出过 riscv64 版本的 node.js，(一上来就是问题)。所以找了另一个非官方的……unofficial-builds.nodejs.org，执行如下命令安装；

# 以 v22.21.1 为例（v20+ 在 JH7110S 上实测可用）
cd ~
wget https://unofficial-builds.nodejs.org/download/release/v22.21.1/node-v22.21.1-linux-riscv64.tar.xz

tar -xvf node-v22.21.1-linux-riscv64.tar.xz
sudo cp -r node-v22.21.1-linux-riscv64/{bin,include,lib,share} /usr/local/

# 验证
node -v
npm -v

安装 Hermes Agent

一键安装命令，这是官方 linux 布署指令，但这个命令在 riscv64 上 100% 会报错。不要慌！

cd
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装 rustup（RISC-V64 官方支持）

版本要大于 1.78，否则 build 会报错。

# 下载 rustup 安装脚本
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o rustup-init.sh

# 执行安装，默认安装 stable 工具链
bash rustup-init.sh -y --default-toolchain stable

# 加载环境变量
source $HOME/.cargo/env

# 验证版本
rustc --version   # 应显示 1.86+（2026年6月最新稳定版）
cargo --version   # 同步显示

配置 UV

安装 uv

cd ~/.hermes/hermes-agent  # 或你的项目目录
uv lock # 确认是否安装 uv，如果没有，那就继续

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# 安装系统级编译依赖（非常关键）
sudo apt update
sudo apt install -y \
    build-essential \
    python3-dev \
    python3-pip \
    libssl-dev \
    libffi-dev \
    libuv1-dev \
    cmake \
    pkg-config \
    patchelf
    
    # 同步
    uv sync

配置 QRcode

安装 Pillow 核心依赖，这个 python 包对于 qrcode 很关键，没有安装就会报错，但是它又需要以下这些依赖，否则它安装一样报错。

# 不装 libtiff-dev（避免拉入 libdeflate-dev），其他都装
sudo apt install -y \
    libjpeg-dev \
    zlib1g-dev \
    libpng-dev \
    libwebp-dev \
    liblcms2-dev \
    libopenjp2-7-dev \
    libfreetype-dev \
    python3-dev

安装 qrcode 和 pillow

# 定位 venv 环境，这一步很关键，发现 hermes 会存在两个 venv，所以要搞清楚 hermes 动用的是哪个 venv
cat ~/.hermes/hermes-agent/venv/bin/hermes | head -n 5

# 以下是列出信息
#!/home/user/.hermes/hermes-agent/venv/bin/python3
# -*- coding: utf-8 -*-
import sys
from hermes_cli.main import main
if __name__ == "__main__":

# 用 uv 明确指定 venv 的 Python 路径来安装
cd ~/.hermes/hermes-agent
uv pip install --python venv/bin/python3 "qrcode[pil]" pillow

配置 Hermes Agent

以上配置全部完成后，执行……

hermes setup

# 后续配置模型和 gateway 全部按照实际指示来。只要 Hermes 运行起来，有任何配置问题都可以让 Hermes 修复。
3 Likes
2

现 Hermes 升级到 v0.16 过程中会遇到 npm error，需要把 nodejs 升级到 24.16，可进行让如下操作升级 nodejs

# 1. 下载 v24.16.0 riscv64 包
cd ~
wget https://unofficial-builds.nodejs.org/download/release/v24.16.0/node-v24.16.0-linux-riscv64.tar.xz

# 2. 解压到 /usr/local
sudo tar -xJf node-v24.16.0-linux-riscv64.tar.xz -C /usr/local/

# 3. 创建软链接或更新 PATH
sudo ln -sf /usr/local/node-v24.16.0-linux-riscv64/bin/node /usr/local/bin/node
sudo ln -sf /usr/local/node-v24.16.0-linux-riscv64/bin/npm /usr/local/bin/npm
sudo ln -sf /usr/local/node-v24.16.0-linux-riscv64/bin/npx /usr/local/bin/npx

# 4. 验证
node -v   # 应输出 v24.16.0
npm -v