milkv Mars

# Fedora 42 RISC-V (JH7110) OpenClaw 完整部署指南

> 适用设备：VisionFive2 / Milk-V Mars 同类 JH7110 SoC  
> 系统：Fedora 42 Server (riscv64)  
> Node.js: 22.x  
> 更新时间：2026-02-26

---

## 一、环境准备

### 1.1 基础依赖安装

```bash
# 更新系统
sudo dnf -y update

# 安装开发工具组
sudo dnf -y install @development-tools

# 安装编译依赖
sudo dnf -y install \
  git curl wget which tar xz unzip \
  cmake ninja-build make gcc gcc-c++ \
  python3 python3-pip pkgconf-pkg-config \
  openssl-devel zlib-devel libstdc++-devel \
  glibc-langpack-en ca-certificates
```

### 1.2 验证 Node.js 版本

```bash
node -v  # 必须 v22.x
npm -v
```

---

## 二、关键环境变量配置

### 2.1 创建环境文件

```bash
# 创建配置目录
sudo mkdir -p /etc/openclaw

# 创建 llama.cpp 编译参数（关闭所有 RISC-V 特性）
cat <<'EOF' | sudo tee /etc/openclaw/openclaw.env
NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RVV=OFF
NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZICBOP=OFF
NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZIHINTPAUSE=OFF
NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZVFH=OFF
NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZFH=OFF
NODE_LLAMA_CPP_CMAKE_OPTION_GGML_VULKAN=OFF
NODE_LLAMA_CPP_CMAKE_OPTION_GGML_OPENCL=OFF
EOF

# 创建 shell profile（可选，用于交互 shell）
cat <<'EOF' | sudo tee /etc/profile.d/openclaw.sh
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RVV=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZICBOP=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZIHINTPAUSE=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZVFH=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZFH=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_VULKAN=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_OPENCL=OFF
EOF
```

### 2.2 加载环境变量

```bash
source /etc/profile.d/openclaw.sh
```

---

## 三、OpenClaw 安装（关键步骤）

### 3.1 清除可能导致问题的配置

```bash
# 关闭全局 build_from_source（否则 sharp 会强制源码编译失败）
unset npm_config_build_from_source
npm config delete build_from_source || true

# 关闭 sharp 使用系统 libvips（Fedora 的 vips 版本太旧）
unset SHARP_FORCE_GLOBAL_LIBVIPS
unset npm_config_sharp_force_global_libvips
export SHARP_IGNORE_GLOBAL_LIBVIPS=1
export npm_config_sharp_ignore_global_libvips=true
```

### 3.2 安装 OpenClaw

```bash
# 清理旧安装
rm -rf /opt/node22/lib/node_modules/openclaw
npm cache clean --force

# 首次安装（不使用全局 build_from_source）
npm install -g openclaw --verbose
```

### 3.3 单独编译 node-llama-cpp（带 RISC-V OFF 参数）

```bash
# 设置 llama.cpp 编译参数
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RVV=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZICBOP=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZIHINTPAUSE=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZVFH=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_RV_ZFH=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_VULKAN=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_OPENCL=OFF

# 仅重编 node-llama-cpp
cd /opt/node22/lib/node_modules/openclaw
npm rebuild node-llama-cpp --verbose
```

---

## 四、验证安装

```bash
# 检查 CLI
openclaw --help
openclaw --version

# 启动 Gateway
openclaw gateway start

# 检查状态
openclaw gateway status
openclaw status
```

---

## 五、systemd 服务化（开机自启）

### 5.1 创建服务文件

```bash
sudo tee /etc/systemd/system/openclaw-gateway.service > /dev/null <<'EOF'
[Unit]
Description=OpenClaw Gateway Service
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
User=fedora
Group=fedora
EnvironmentFile=/etc/openclaw/openclaw.env
Environment=HOME=/home/fedora
Environment=PATH=/usr/local/bin:/usr/bin:/bin:/home/fedora/.npm-global/bin
WorkingDirectory=/home/fedora
ExecStart=/usr/bin/env bash -lc 'openclaw gateway start'
ExecStop=/usr/bin/env bash -lc 'openclaw gateway stop'
ExecReload=/usr/bin/env bash -lc 'openclaw gateway restart'
TimeoutStartSec=120
TimeoutStopSec=60

[Install]
WantedBy=multi-user.target
EOF
```

### 5.2 启用并启动服务

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway.service

# 检查状态
systemctl status openclaw-gateway.service --no-pager
systemctl is-enabled openclaw-gateway.service
systemctl is-active openclaw-gateway.service
```

---

## 六、故障排查

### 6.1 sharp 编译失败（libvips 版本问题）

**错误信息：**
```
#error "libvips version 8.17.3+ is required"
```

**解决方案：**
```bash
# 强制 sharp 使用自带 libvips，忽略系统版本
export SHARP_IGNORE_GLOBAL_LIBVIPS=1
export npm_config_sharp_ignore_global_libvips=true

# 清理重装
rm -rf /opt/node22/lib/node_modules/openclaw
npm cache clean --force
npm install -g openclaw --verbose
```

### 6.2 node-llama-cpp 编译失败（Vulkan 问题）

**错误信息：**
```
Could NOT find Vulkan (missing: Vulkan_LIBRARY Vulkan_INCLUDE_DIR glslc)
```

**解决方案：**
```bash
# 确保环境变量正确设置
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_VULKAN=OFF
export NODE_LLAMA_CPP_CMAKE_OPTION_GGML_OPENCL=OFF

# 重新编译
cd /opt/node22/lib/node_modules/openclaw
npm rebuild node-llama-cpp --verbose
```

### 6.3 查看日志

```bash
# systemd 日志
journalctl -u openclaw-gateway.service -n 200 --no-pager
journalctl -u openclaw-gateway.service -f

# npm 日志
ls -t /home/fedora/.npm/_logs/*-debug-0.log | head -n1
tail -n 200 $(ls -t /home/fedora/.npm/_logs/*-debug-0.log | head -n1)
```

---

## 七、核心注意事项

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| sharp 编译失败 | Fedora vips 8.15.x < 8.17.3 | 设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` |
| node-llama-cpp 编译失败 | Vulkan/OpenCL 检测 | 设置对应 `CMAKE_OPTION=OFF` |
| 全局 build_from_source=true | 强制所有包源码编译 | `unset npm_config_build_from_source` |
| 环境变量不生效 | 未写入系统文件 | 写入 `/etc/openclaw/openclaw.env` |

---

## 八、快速参考命令

```bash
# 启动
openclaw gateway start

# 停止
openclaw gateway stop

# 重启
openclaw gateway restart

# 状态
openclaw gateway status

# 查看日志
journalctl -u openclaw-gateway.service -f
```

---

*文档由 OpenClaw 部署过程自动生成*