openEuler 24.03 安装 UKUI + Node.js v26.2.0 + OpenClaw 完整过程文档

一、环境概述

openEuler 24.03 LTS 基于 Linux 6.6 内核，支持 x86_64 和 aarch64 两种架构。UKUI 是麒麟软件团队打造的 Linux 桌面环境，与 openEuler 集成良好，界面类似 Windows，适合国内用户。

二、安装 UKUI 桌面环境

2.1 前提条件

• 已安装 openEuler 24.03 系统（最小化安装或 Server 版本均可）

• 系统网络连接正常

• 具有 root 权限或 sudo 权限

• 建议在安装 UKUI 前创建一个普通管理员用户（root 用户默认不可直接登录桌面）

2.2 更新系统软件包

首先更新系统中所有已安装的软件包到最新版本：

bash

sudo dnf update -y

-y 参数表示自动确认，无需手动确认每个步骤。

2.3 安装 UKUI

执行以下命令安装 UKUI 桌面环境：

bash

sudo dnf -y install ukui

该命令会自动解析并安装所有依赖项。UKUI 支持 x86_64 和 aarch64 两种架构，安装过程约需 10 分钟左右。

说明：也可使用 sudo dnf -y install ukui-desktop-environment 进行标准安装，两者效果基本一致。

2.4 设置图形界面为默认启动

安装完成后，设置系统默认以图形界面方式启动：

bash

sudo systemctl set-default graphical.target

然后重启系统：

bash

sudo reboot

重启后系统将自动进入 UKUI 图形登录界面。

2.5 手动切换界面模式

如需手动切换图形界面和命令行界面，可使用以下命令：

bash

# 切换到图形界面（runlevel 5）
sudo init 5

# 切换到命令行界面（runlevel 3）
sudo init 3

2.6 允许 root 用户登录桌面（可选）

默认情况下，root 用户无法登录 UKUI 桌面环境。如需启用 root 桌面登录，编辑 LightDM 配置文件：

bash

sudo vim /etc/lightdm/lightdm.conf

找到并修改以下配置项：

ini

greeter-show-manual-login=true
allow-user-switching=true
allow-guest=true

保存退出后重启系统，即可在登录界面手动输入 root 用户名和密码登录。

安全提示：出于安全考虑，不建议在生产环境中允许 root 用户直接登录图形桌面，建议始终使用普通用户登录。

2.7 验证安装

系统重启后，应看到 UKUI 图形登录界面。登录后，在终端中执行以下命令确认桌面环境：

bash

echo $XDG_CURRENT_DESKTOP

输出应为 UKUI。

2.8 卸载 UKUI（如需）

bash

sudo dnf -y remove ukui
# 或
sudo dnf -y remove ukui-desktop-environment

三、安装 Node.js v26.2.0

3.1 安装方式选择

openEuler 24.03 默认软件源中的 Node.js 版本通常较低（约 v20.x），无法满足 OpenClaw 对 Node.js ≥ v22 的要求。因此需要手动安装指定版本。

本教程采用官方二进制包手动安装方式（推荐），步骤如下：

3.2 下载 Node.js v26.2.0 二进制包

访问 Node.js 官方分发站点下载对应架构的预编译二进制包。以 x86_64 架构为例：

bash

cd /tmp
wget https://nodejs.org/dist/v26.2.0/node-v26.2.0-linux-x64.tar.xz

AArch64 架构（如鲲鹏处理器）请将下载链接中的 linux-x64 替换为 linux-arm64。

加速下载：国内用户可使用镜像站（如 https://npmmirror.com/mirrors/node/v26.2.0/ ）加速下载。

3.3 解压并安装

将二进制包解压到 /usr/local/ 目录下：

bash

sudo tar -xJf node-v26.2.0-linux-x64.tar.xz -C /usr/local/

解压后的目录结构为 /usr/local/node-v26.2.0-linux-x64/，内含 bin/、lib/、include/ 等子目录。

3.4 配置环境变量

方法一：创建软链接（推荐）

bash

sudo ln -s /usr/local/node-v26.2.0-linux-x64/bin/node /usr/local/bin/node
sudo ln -s /usr/local/node-v26.2.0-linux-x64/bin/npm /usr/local/bin/npm
sudo ln -s /usr/local/node-v26.2.0-linux-x64/bin/npx /usr/local/bin/npx

创建软链接后，由于 /usr/local/bin 通常已在系统 PATH 中，任意目录下均可直接使用 node、npm、npx 命令。

方法二：配置系统环境变量（全局生效）

编辑 /etc/profile 文件：

bash

sudo vim /etc/profile

在文件末尾添加：

bash

export NODE_HOME=/usr/local/node-v26.2.0-linux-x64
export PATH=$PATH:$NODE_HOME/bin

保存后刷新配置：

bash

source /etc/profile

3.5 验证安装

bash

node -v    # 应输出 v26.2.0
npm -v     # 应输出对应的 npm 版本号
npx -v     # 应输出对应的 npx 版本号

3.6 配置 npm 国内镜像源（推荐）

为加速后续包的下载，建议配置 npm 国内镜像源：

bash

npm config set registry https://registry.npmmirror.com

或使用华为云镜像：

bash

npm config set registry https://mirrors.huaweicloud.com/repository/npm/

验证配置：

bash

npm config get registry

四、安装 OpenClaw

4.1 OpenClaw 简介

OpenClaw 是一个自托管的个人 AI 助手网关框架，核心理念是本地优先、多通道接入、执行而不只是聊天。它能够将多个聊天平台（Telegram、WhatsApp、Discord、飞书、钉钉等）连接到同一个 AI 助手，并通过技能系统实现代码运行、文件管理、网页搜索等自动化操作。

4.2 系统要求

OpenClaw 对硬件配置要求较为宽松，2核4G即可流畅运行。

4.3 安装方式

OpenClaw 提供两种主流安装方式：官方一键脚本安装和 npm 全局安装。

方式一：官方一键脚本安装（最推荐，适合新手）

适用于 Linux / macOS 系统，脚本会自动检测并安装 Node.js 及所有依赖：

bash

curl -fsSL https://openclaw.ai/install.sh | bash

安装完成后，按照终端提示完成初始配置向导。

方式二：npm 全局安装（本教程采用）

bash

npm install -g openclaw@latest

如果安装过程中遇到权限问题（EACCES permission denied），可通过以下方式解决：

bash

npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw@latest

验证安装：

bash

openclaw --version

4.4 运行 Onboard 初始化向导

Onboard 向导是 OpenClaw 官方提供的交互式配置工具，可自动完成 Gateway 守护进程注册、初始配置文件创建和健康检查：

bash

openclaw onboard --install-daemon

向导会依次引导完成以下配置：

1. 选择安装位置：默认 ~/.openclaw/，直接回车使用默认值

2. 注册守护进程：Linux 下将写入 ~/.config/systemd/user/openclaw-gateway.service

3. API Key 初始配置：选择模型提供商并填入 API Key

4. 健康检查：自动运行 openclaw doctor 验证配置

5. Gateway 自动启动：向导完成后 Gateway 会自动启动

配置过程中，建议选择：

• 模型：根据需求选择 Moonshot AI（Kimi）、OpenAI、Anthropic 等。国内用户推荐选择 Moonshot AI .cn 接入点

• 技能（Skills）：按需选择，推荐勾选网络搜索等常用技能

• 聊天载体：可先选择 TUI（终端界面）进行体验

4.5 手动配置 API Key

若跳过向导，也可手动编辑配置文件：

配置文件位置：~/.openclaw/config.yaml

auth-profiles.json 配置文件路径：

text

~/.openclaw/agents/main/agent/auth-profiles.json

示例配置（以 Moonshot AI / Kimi 为例）：

json

{
  "profiles": [
    {
      "id": "kimi-main",
      "type": "api-key",
      "provider": "moonshot",
      "apiKey": "你的Kimi-API-Key",
      "model": "moonshot-v1-128k"
    }
  ],
  "default": "kimi-main"
}

4.6 启动 Gateway 服务

bash

openclaw gateway start
# 或指定端口（默认 18789）
openclaw gateway --port 18789 --verbose

4.7 验证 Gateway 运行状态

bash

# 查看 Gateway 状态
openclaw gateway status

# 测试健康端点
curl -s http://127.0.0.1:18789/health | python3 -m json.tool

# 查看实时日志
openclaw logs --follow --level info

正常输出应包含 "status": "ok"。

4.8 使用 TUI 体验

bash

openclaw tui

进入终端交互界面后即可与 AI 助手进行对话。按两次 Ctrl+C 可退出 TUI。

4.9 Gateway 常用控制命令

bash

openclaw gateway start      # 启动
openclaw gateway stop       # 停止
openclaw gateway restart    # 重启（配置修改后使用）
openclaw gateway status     # 查看状态
openclaw doctor             # 诊断工具
openclaw status             # 查看运行状态

4.10 配置防火墙（如需远程访问）

如果需要在其他设备上访问 OpenClaw Gateway，需开放相应端口：

bash

sudo firewall-cmd --add-port=18789/tcp --permanent
sudo firewall-cmd --reload

安全提示：生产环境中建议采用白名单策略，仅放行必要 IP 段的访问权限。

4.11 OpenClaw 中开启“思考”功能

在 OpenClaw 中开启“思考”功能，主要有两种方式：一种是控制“想得多深”的 /think 功能，另一种是控制“看得到过程”的 /reasoning 功能。

/think：控制思考深度 (Think Harder)

这个功能控制模型的“思考预算”，它会直接影响模型在处理问题前投入多少计算资源进行内部推理。请根据你的任务选择合适的级别：

注意：思考过程本身也消耗Token，高级别会显著增加。但/think控制的内部推理过程默认是隐藏的，不直接显示在界面上。

如何开启 /think

你可以在三种场景下使用该命令：

• 临时开启（单次）：在问题前加上 /think:high，效果只影响当前这条消息。

  text

  /think:high 请帮我分析这份合同中的潜在法律风险。

  
  

• 会话开启（持续）：单独发送一条 /think:medium 消息，后续在当前会话中都生效。

• 全局开启（永久）：通过修改配置文件设置全局默认的思考级别。

  bash

  openclaw config set agents.defaults.thinkingDefault high
  openclaw gateway restart

  
  

/reasoning：显示思维链 (Show Your Work)

这个功能用于控制模型的思考过程是否直接显示，不影响模型本身的思考质量，只影响透明度。支持以下级别：

如何开启 /reasoning

使用方法与 /think 类似：

• 临时开启：在消息前加上 /reasoning:on 即可。

• 会话开启：单独发送一条 /reasoning:on 的命令。

  text

  /reasoning:on

  
  

注意：部分模型（如DeepSeek-R1）本身就支持展示内部思考过程，通过这个命令可以更方便地控制其显示。

组合使用

你可以将 /think high（深度思考）和 /reasoning:on（显示过程）组合使用。这样既能获得高质量的答案，又能清晰地看到AI是如何一步步得出结论的。

补充细节

• /verbose (详细模式)：这个命令主要用于调试工具调用（如浏览器、代码执行等）。开启它（/verbose on）可以看到工具名、传入参数和返回结果等详细信息，非常适合排查功能性问题。

• 命令优先级：规则的生效优先级是：临时命令 > 会话命令 > 全局配置，临时命令的优先级是最高的。

五、常见问题排查

5.1 UKUI 安装失败

bash

# 检查网络连通性
ping -c 4 www.baidu.com

# 清理 dnf 缓存后重试
sudo dnf clean all
sudo dnf makecache
sudo dnf -y install ukui

5.2 UKUI 桌面黑屏或无法启动

bash

# 检查显示管理器状态
sudo systemctl status lightdm

# 若未启动，手动启动
sudo systemctl start lightdm
sudo systemctl enable lightdm

5.3 Node.js 命令未找到

bash

# 确认软链接是否正确
ls -la /usr/local/bin/node /usr/local/bin/npm

# 确认 PATH 环境变量
echo $PATH

# 手动添加（临时生效）
export PATH=/usr/local/node-v26.2.0-linux-x64/bin:$PATH

5.4 OpenClaw 命令未找到

bash

# 检查 Node.js 版本
node -v

# 检查全局包路径
npm prefix -g

# 确认全局 bin 目录是否在 PATH 中
echo $PATH

# 若不在，手动添加
echo 'export PATH=$(npm prefix -g)/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

5.5 Gateway 启动失败

bash

# 运行诊断工具
openclaw doctor

# 查看详细日志
openclaw logs --follow --level debug

# 确认端口未被占用
sudo ss -tlnp | grep 18789

六、完整安装流程速查表

bash

# ===== 第一步：更新系统 =====
sudo dnf update -y

# ===== 第二步：安装 UKUI 桌面 =====
sudo dnf -y install ukui
sudo systemctl set-default graphical.target
sudo reboot

# ===== 第三步：安装 Node.js v26.2.0 =====
wget https://nodejs.org/dist/v26.2.0/node-v26.2.0-linux-x64.tar.xz
sudo tar -xJf node-v26.2.0-linux-x64.tar.xz -C /usr/local/
sudo ln -s /usr/local/node-v26.2.0-linux-x64/bin/node /usr/local/bin/node
sudo ln -s /usr/local/node-v26.2.0-linux-x64/bin/npm /usr/local/bin/npm
npm config set registry https://registry.npmmirror.com

# ===== 第四步：安装 OpenClaw =====
npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw gateway start
openclaw tui

参考资源：

• openEuler 官方文档：https://docs.openeuler.org[reference:24]

• UKUI 用户指南：https://gitee.com/openeuler/ukui[reference:25]

• Node.js 官方下载：https://nodejs.org/dist/

• OpenClaw 官方文档：https://docs.openclaw.ai/start/getting-started[reference:26]