OpenClaw在Ubuntu中安装

一、环境要求

要部署openClaw，你需要满足一系列硬件和软件要求。openClaw是一个开源项目，主要用于机器人控制和仿真。它通常与ROS（Robot Operating System）结合使用，特别是在机器人研究和开发中。下面是一些基本的部署环境要求：

硬件要求

1. ‌处理器‌：
   • 建议使用至少四核的CPU，例如Intel Core i5或更高版本。
2. ‌内存‌：
   • 至少8GB RAM，对于复杂的机器人应用或仿真，可能需要更多。
3. ‌存储‌：
   • SSD（固态硬盘）提供更快的读写速度，推荐至少256GB的存储空间。
4. ‌**图形处理单元（GPU）**‌：
   • 对于需要高性能图形处理的应用（如使用Unity进行机器人仿真），建议使用NVIDIA的GPU，并安装支持CUDA的驱动。
5. ‌其他接口‌：
   • 根据你的机器人硬件配置，可能需要USB、串口或其他接口。

软件要求

1. ‌操作系统‌：
   • openClaw和ROS主要支持Linux（如Ubuntu），因为它们在Linux上得到了最好的支持和优化。Windows和macOS的支持相对较少，但可以通过特定的配置和工具链实现。
2. ‌ROS版本‌：
   • openClaw通常与ROS 1或ROS 2一起使用。确保安装了与openClaw兼容的ROS版本。例如，openClaw可能特别针对ROS Noetic或ROS 2 Galactic进行了优化。
3. ‌依赖软件‌：
   • 安装必要的库和工具，如Gazebo（用于仿真）、MoveIt!（用于路径规划和运动控制）等。
   • Python环境，通常需要Python 3.x版本，以及pip用于安装Python包。
   • Node版本 ≥ 22

二、环境准备

虚拟机：VMware Workstation Pro 17

Linux系统：Ubuntu 22.04.5 LTS

窗口系统：Wayland

预设内存：12G

预设存储空间：100G（因为我虚拟机中运行了很多其他服务所以存储空间设置的比较大，实际可以按照自己设备空间自行规划，考虑后续可能会继续添加其他功能，建议分配空间不要低于20G）

三、安装步骤（以本机Ubuntu22.04为例）

1.安装ROS 2 Humble

Tips:如果不需要机器人研究和开发中使用可以跳过这一步

#  第一步：准备环境 (设置语言与开启源)
# 1.1 确保系统支持UTF-8：ROS 2 需要支持 UTF-8 的语言环境，我们先进行设置。
# 如果使用 `locale`命令发现语言已经是UTF-8则跳过后续设置操作
locale  # 检查当前语言设置

sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

locale  # 验证设置是否生效

# 1.2 添加必要的软件源：确保Ubuntu Universe存储库已开启。
sudo apt install software-properties-common
sudo add-apt-repository universe

#  第二步：添加ROS 2 软件源
# 2.1 添加ROS 2 的GPG密钥：
sudo apt update && sudo apt install curl -y
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

# 2.2 将ROS 2 仓库添加到源列表：
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

#  第三步：安装ROS 2 Humble
# 3.1 更新软件包列表并升级系统：
sudo apt update
sudo apt upgrade

# 3.2 安装ROS 2 Humble桌面版：
# `ros-humble-desktop` 这个包包含了ROS 2的核心功能、2D/3D感知功能（比如rviz2）以及一些示例程序，非常适合初学者和大多数开发者。
sudo apt install ros-humble-desktop

# 3.3 安装开发工具：
# 这个工具包提供了 `ros2` 命令行工具以及其他编译和构建工作空间时需要用到的工具。
sudo apt install ros-dev-tools

# 第四步：设置环境变量
# 为了方便，每次打开新终端时自动加载ROS 2的环境变量。

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

验证安装

为了确保一切顺利，我们来运行一个经典的“Hello World”示例——C++和Python节点的通信。

1. 运行C++发布者节点：
   在当前的终端中，直接输入以下命令：

   ros2 run demo_nodes_cpp talker
   

   如果安装成功，你会看到终端开始不断输出 [INFO] [.....] [talker]: Publishing: 'Hello World: N' 这样的信息。

2. 运行Python订阅者节点：
   请另外打开一个新的终端，同样因为我们已经配置了环境变量，可以直接运行：

   ros2 run demo_nodes_py listener
   

   在这个新终端里，你应该能看到它正在接收来自第一个终端发布的消息，并输出 [INFO] [.....] [listener]: I heard: [Hello World: N]。

看到这两个终端能成功收发消息，就证明你的ROS 2 Humble环境已经完美安装并配置好啦！

2.安装Node

OpenClaw依赖Node.js（版本≥22），推荐使用nvm（Node版本管理工具）安装，避免版本冲突：

# 1. 系统更新（确保依赖兼容，避免安装失败）
sudo apt update && sudo apt upgrade -y

# 2. 安装nvm（Node版本管理工具，选择v0.40.4稳定版）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

# 3. 生效nvm（无需重启终端，执行命令即可加载）
source ~/.bashrc

# 4. 安装Node.js 22（官方推荐最低版本，也可安装23版本）
nvm install 22

# 5. 设置Node.js 22为默认版本
nvm use 22

# 6. 验证安装结果（显示版本号≥22即为成功）
node --version  # 预期输出：v22.x.x（如v22.10.0）
npm --version   # 预期输出：10.x.x及以上

# 7. 安装pnpm（推荐包管理器，安装速度更快，依赖处理更优）
npm install -g pnpm

3.OpenClaw安装（3种方式任选）

OpenClaw提供脚本安装、npm/pnpm安装、源码安装3种方式，新手优先选择脚本安装，一键完成配置：

方式1：脚本一键安装（新手首选）

# 执行官方一键安装脚本，自动下载最新稳定版
curl -fsSL https://openclaw.ai/install.sh | bash

# 验证安装结果（显示版本号即为成功）
openclaw --version  # 预期输出：2026.2.x及以上

方式2：npm/pnpm全局安装（脚本安装失败备选）

# npm安装（已安装Node.js默认自带npm）
npm install -g openclaw@latest

# 或pnpm安装（推荐，速度更快）
pnpm add -g openclaw@latest

# 验证安装
openclaw --version

方式3：源码安装（进阶用户，获取开发版功能）

适合需要自定义开发或体验最新功能的用户：

# 1. 克隆OpenClaw仓库
git clone https://github.com/openclaw/openclaw.git

# 2. 进入项目目录
cd openclaw

# 3. 安装依赖（推荐pnpm）
pnpm install

# 4. 构建项目
pnpm build

# 5. 链接到全局，方便终端调用
pnpm link --global

# 6. 验证安装
openclaw --version

4.基础配置：新手引导向导（必做）

安装完成后，通过新手引导向导快速完成模型配置、网关设置等核心步骤：

# 启动新手引导向导，并安装后台守护进程（开机自启）
openclaw onboard --install-daemon

跟着向导完成以下5步配置（全程交互式，按提示操作即可）：

1. 模型配置：选择需要对接的AI模型（如Kimi、豆包、OpenAI），按提示输入API密钥完成授权；
2. 工作区配置：默认路径为~/.openclaw/workspace，无需修改，直接确认即可（用于存储配置、技能、任务数据）；
3. 通道配置：暂时跳过，后续专门配置飞书通道；
4. 守护进程安装：确认安装Gateway守护进程，让OpenClaw在后台持续运行，支持开机自启；
5. 完成配置：向导自动保存所有设置，无需手动操作。

5.Gateway网关启动与验证

Gateway是OpenClaw的控制中枢，负责管理插件、通道与模型调用，新手引导中已自动安装守护进程：

# 验证Gateway状态（显示"running"即为正常运行）
openclaw gateway status

# 若未运行，执行以下命令启动
openclaw gateway start

# 前台运行并查看日志（便于排查问题，按Ctrl+C停止）
openclaw gateway --port 18789 --verbose

启动成功后，可通过浏览器访问仪表盘：

1. 打开浏览器，输入地址：http://127.0.0.1:18789/；

2. 输入网关令牌（默认存储在~/.openclaw/openclaw.json中，搜索token字段即可找到）；

3. 成功进入聊天界面，说明本地安装与配置完成。

   Tips:跟随向导安装完成后控制台会打印出Control UI 视图，里面有拼接好的带有token的完整地址
   
   可通过以下命令快速查询（Linux/macOS/阿里云容器内通用）：

   # 方式1：直接查询配置文件中的Token
   cat ~/.openclaw/openclaw.json | grep "gateway.auth.token"
   
   # 方式2：通过OpenClaw命令生成带Token的Dashboard链接
   openclaw dashboard --no-open
   
   

   执行后会输出类似结果：http://127.0.0.1:18789/?token=5be6d24e69262af869364c4fe2298b5128d19c43c8d7fa38，其中?token=后的字符串即为Gateway Token，需妥善保存。

问题:该地址仅支持本地网络访问。若需在外部网络环境下管理网关，官方文档提示我们需借助 Tailscale 或 VPN 等代理工具，但这些方式在国内网络环境中往往体验不佳。参考文档

因此使用内网穿透工具辅助我们访问与调试

6.ZeroNews实现OpenClaw Dashboard远程访问配置

ZeroNews远程映射分为Agent安装、域名创建、映射配置三步，支持Linux、Windows、macOS、NAS等所有部署OpenClaw的设备，本文以Linux为例，其他系统操作逻辑一致。ZeroNews访问地址

第一步： Claw设备上安装ZeroNews Agent

Agent是ZeroNews实现公网映射的核心组件，需安装在部署OpenClaw的同一台设备上，实现本地服务与公网的连接。

# 1. 一键安装ZeroNews Agent（支持Debian/Ubuntu/RHEL/CentOS/AlmaLinux）
curl -Slk https://download.zeronews.cc/linux/zeronews-install.sh | sudo sh -s install

# 2. 配置ZeroNews Token（从ZeroNews官网控制台获取）
sudo zeronews set token 你的ZeroNews Token

# 3. 启动Agent并设置开机自启（后台运行，避免终端关闭停止）
sudo systemctl enable zeronews
sudo systemctl start zeronews

# 4. 验证Agent状态（显示active (running)即为正常）
sudo systemctl status zeronews

Windows/macOS安装：前往ZeroNews官网下载对应系统的Agent安装包，手动安装后完成Token配置，启动后在控制台查看Agent在线状态。

第二步：在ZeroNews控制台创建专属公网域名

登录ZeroNews官网控制台，创建适配OpenClaw的公网域名，默认开启HTTPS加密，无需手动配置证书。

1. 进入域名端口页面，点击新增域名端口；

2. 配置参数：

   • 域名前缀：自定义（如myopenclaw，仅含字母/数字/下划线）；
   • 协议选择：默认勾选HTTPS(web:443)（必须，OpenClaw Dashboard适配HTTPS）；
   • 域名备注：填写OpenClaw Dashboard远程访问（便于管理）；

3. 点击确认，生成专属公网域名（如myopenclaw.dy.takin.cc），该域名将作为远程访问Dashboard的入口。

第三步：配置ZeroNews映射规则，关联OpenClaw服务

进入ZeroNews控制台映射页面，创建映射规则，将本地OpenClaw服务与公网域名绑定，实现外网访问。

1. 点击 添加映射，配置核心参数：

   • 选择Agent：选择已安装并在线的ZeroNews Agent（对应部署OpenClaw的设备）；
   • 映射协议：选择HTTPS（与域名协议一致）；
   • 域名：选择步骤2创建的专属公网域名；
   • 映射带宽：个人用户选择2Mbps即可，企业用户可按需升级；
   • 内网IP：填写127.0.0.1（本地部署，若为局域网服务器填写设备内网IP）；
   • 内网端口：填写18789（OpenClaw Gateway默认端口，不可修改）；

2. 点击确认，等待1-2分钟，映射规则生效，状态显示已启用。

第四步：远程访问初步验证

打开任意外网环境的浏览器，输入创建的公网域名（如https://myopenclaw.dy.takin.cc），若能打开OpenClaw Dashboard界面（即使显示断开连接），说明映射配置成功；若无法打开，检查Agent状态、映射端口、域名协议是否配置正确。

四、远程访问两大核心错误（Token缺失+设备授权）

远程访问OpenClaw Dashboard时，最常出现Gateway Token缺失（1008错误） 和设备授权失败（pairing required） 两大问题，均为OpenClaw的安全机制导致，按以下步骤可快速解决。

（一）错误1：Gateway Token缺失（报错：disconnected (1008): unauthorized: gateway token missing）

错误原因

OpenClaw Dashboard的远程访问需要验证Gateway Token，首次外网访问时浏览器未缓存Token，导致认证失败，属于正常安全校验。

错误图片

解决方案（可视化操作，无需命令）

1. 在外网浏览器中打开远程Dashboard，进入Control/Overview（控制/概览）页面；

2. 找到Gateway Token输入框，粘贴之前获取的OpenClaw Gateway Token；

3. 确认WebSocket URL为当前公网域名（如wss://myopenclaw.dy.takin.cc），无需修改；

4. 点击下方Connect按钮，等待3-5秒，页面STATUS从Disconnected变为Connected，即完成Token认证，可正常使用所有功能。

（二）错误2：设备授权失败（报错：disconnected (1008): pairing required）

错误原因

OpenClaw开启了设备配对安全机制，新设备/新浏览器首次访问Dashboard时，需要管理员在OpenClaw部署设备上进行授权，防止未授权设备访问，是比Token更高级的安全防护。

错误图片

解决方案（命令行+可视化配合，四步完成）

操作前提：在部署OpenClaw的设备上执行命令（本地Linux/Windows终端、阿里云服务器/容器内），确保设备与OpenClaw服务正常连接。

# 步骤1：查询待授权设备列表，获取Request ID
openclaw devices list

执行后终端会显示Pending（待授权） 列表，包含1条待授权设备记录，记录下Request ID（一串字母+数字组合，如f9766acc3c941e8aa7b8a532）。

# 步骤2：执行设备授权命令（替换为实际的Request ID）
openclaw devices approve <你的Request ID>

# 步骤3：重启OpenClaw网关，使授权生效
openclaw gateway restart
# 可选：验证授权结果，待授权列表消失即为成功
openclaw devices list

步骤4：回到外网浏览器的Dashboard页面，点击Refresh（刷新）按钮，STATUS变为Connected/正常，设备授权完成，可正常远程操作。

（三）设备授权补充说明

1. 授权持久性：设备授权后会被永久记录，除非手动撤销，后续使用同一浏览器/设备访问无需重新授权；

2. 重新授权场景：切换浏览器、清除浏览器缓存、更换设备，会生成新的设备ID，需要重新执行授权步骤；

3. Request ID过期：若等待授权时间过长（超过5分钟），Request ID会失效，需在Dashboard点击Connect重新触发申请，再执行命令授权；

4. 撤销设备授权

   ：若设备丢失/不再使用，执行以下命令撤销授权，保障安全：

   # 撤销指定设备授权（device ID从openclaw devices list的Paired列表中查询）
   openclaw devices revoke --device <设备ID> --role operator
   

三）设备授权补充说明

1. 授权持久性：设备授权后会被永久记录，除非手动撤销，后续使用同一浏览器/设备访问无需重新授权；

2. 重新授权场景：切换浏览器、清除浏览器缓存、更换设备，会生成新的设备ID，需要重新执行授权步骤；

3. Request ID过期：若等待授权时间过长（超过5分钟），Request ID会失效，需在Dashboard点击Connect重新触发申请，再执行命令授权；

4. 撤销设备授权

   ：若设备丢失/不再使用，执行以下命令撤销授权，保障安全：

   # 撤销指定设备授权（device ID从openclaw devices list的Paired列表中查询）
   openclaw devices revoke --device <设备ID> --role operator