# 在 Ubuntu 20.04 上安装 OpenClaw

在 Ubuntu 20.04 上安装 OpenClaw，推荐使用官方的一键安装脚本，这是最简单快捷的方法。如果遇到问题，也可以采用手动安装方式。

### 🚀 方案一：一键安装（推荐）

官方提供的一键安装脚本会自动完成所有配置，非常适合新手。

1. **执行安装命令**  
    在终端中运行以下命令，脚本将自动下载并安装 OpenClaw 及其所有依赖。 ```bash
    curl -fsSL https://openclaw.ai/install.sh | bash
    
    ```
    
    如果因网络问题导致脚本无法下载，可以尝试使用以下国内镜像源的脚本： ```bash
    curl -fsSL https://gitee.com/openclaw-mirror/install-script/raw/main/install.sh | bash
    
    ```
2. **跟随引导**  
    安装过程中，终端会提示你进行一些基础配置，例如选择模型、配置 Channel 等。通常直接按回车键使用默认选项即可，这些配置后续也可以在 Web 界面中修改。
3. **验证安装**  
    安装成功后，终端会显示 “OpenClaw installed successfully” 并提供控制面板的访问地址（默认为 `http://127.0.0.1:18789/openclaw`）。

### 🛠️ 方案二：手动安装

如果一键安装失败，或者你希望更精细地控制安装过程，可以按照以下步骤手动安装。

#### 1. 环境准备

- **更新系统并安装基础工具**```bash
    sudo apt update && sudo apt upgrade -y
    sudo apt install -y curl git build-essential libssl-dev
    
    ```
- **安装 Node.js (版本 ≥ 22)**  
    OpenClaw 依赖 Node.js 22 或更高版本。使用 NodeSource 源安装是稳定且推荐的方式。 ```bash
    # 导入 NodeSource 22.x 源
    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
    # 安装 Node.js
    sudo apt install -y nodejs
    # 验证安装
    node --version  # 应显示 v22.x.x
    npm --version   # 应显示 10.x.x 或更高
    
    ```
- **配置国内 NPM 镜像（可选）**  
    为加速依赖包下载，建议将 NPM 镜像源切换到国内。 ```bash
    npm config set registry https://registry.npmmirror.com
    
    ```

#### 2. 安装 OpenClaw

- **使用 NPM 全局安装**```bash
    sudo npm install -g openclaw@latest
    
    ```

#### 3. 初始化配置

- **启动初始化向导**  
    安装完成后，运行以下命令来配置模型、API Key 和后台服务等。 ```bash
    openclaw onboard --install-daemon
    
    ```
    
    按照终端提示完成配置即可。

### ⚠️ 常见问题与排查

- **CMake 版本过低**  
    Ubuntu 20.04 默认的 CMake 版本可能低于 OpenClaw 要求的 3.19+，这可能导致编译依赖时出错。如果遇到相关问题，需要手动升级 CMake。
- **防火墙阻止访问**  
    OpenClaw 的控制面板默认使用 **18789** 端口。如果无法通过浏览器访问，请检查并放行该端口。 ```bash
    sudo ufw allow 18789/tcp
    sudo ufw reload
    
    ```
- **命令未找到**  
    如果安装后提示 `openclaw: command not found`，可能是 NPM 的全局路径未被系统识别。可以尝试重新打开终端，或手动创建软链接来解决。

在 Ubuntu 20.04 上，系统默认的 CMake 版本通常是 3.16.x，而 OpenClaw 等现代项目往往要求 3.19+ 甚至更高。

针对你的情况，我推荐**方法一（官方二进制包 + 软链接）**，因为它最安全、快速，且不会破坏系统原有的依赖环境。

### 🚀 方法一：使用官方二进制包（推荐，最快且安全）

这种方法通过下载官方编译好的包，解压后通过“软链接”让系统优先使用新版本，而保留旧版本以防万一。

#### 1. 下载最新版 CMake

首先，我们需要去官网下载最新的预编译包（目前最新版已接近 4.0，这里以 3.28.1 为例，你可以替换为更新的版本号）。

```bash
# 进入临时目录
cd /tmp

# 下载 CMake (请根据需要修改版本号，例如 v3.28.1 或 v3.30.0)
wget https://github.com/Kitware/CMake/releases/download/v3.28.1/cmake-3.28.1-linux-x86_64.tar.gz

```

#### 2. 解压到系统目录

我们将它解压到 `/opt` 目录下，这样比较规范，方便管理。

```bash
# 解压
sudo tar -xzf cmake-3.28.1-linux-x86_64.tar.gz -C /opt/

```

#### 3. 建立软链接（关键步骤）

为了让系统在输入 `cmake` 时调用新版本，我们需要建立软链接。这里推荐使用 `update-alternatives` 工具，它可以优雅地管理多个版本。

```bash
# 注册新版本到 alternatives 系统
# 解释：优先级设为 100 (数字越大优先级越高)
sudo update-alternatives --install /usr/bin/cmake cmake /opt/cmake-3.28.1-linux-x86_64/bin/cmake 100

# 强制更新链接（如果系统提示冲突）
sudo update-alternatives --set cmake /opt/cmake-3.28.1-linux-x86_64/bin/cmake

```

> **备选简单方案：** 如果你不想用 `update-alternatives`，也可以直接用一条简单的命令覆盖（但不如上面的方法灵活）：  
> `sudo ln -sf /opt/cmake-3.28.1-linux-x86_64/bin/cmake /usr/local/bin/cmake`

#### 4. 验证安装

```bash
cmake --version

```

如果输出显示 `cmake version 3.28.1`（或你安装的版本），说明升级成功。

---

### 📦 方法二：使用 Kitware 官方 APT 源（适合习惯 apt 管理的用户）

Kitware（CMake 的开发商）提供了官方的 APT 仓库，可以通过包管理器安装最新版。

1. **安装依赖并导入密钥：**
    
    ```bash
    sudo apt-get install -y software-properties-common lsb-release
    wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg >/dev/null
    
    ```
2. **添加仓库源：**
    
    ```bash
    echo "deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ focal main" | sudo tee /etc/apt/sources.list.d/kitware.list
    
    ```
3. **更新并安装：**
    
    ```bash
    sudo apt-get update
    sudo apt-get install -y cmake
    
    ```

---

### ⚙️ 方法三：源码编译（最慢，仅作为最后手段）

如果上述方法都因系统库版本过老（如 glibc 版本）而失败，你才需要尝试从源码编译。这需要较长时间。

1. **安装编译依赖：**```bash
    sudo apt-get update
    sudo apt-get install -y build-essential libssl-dev
    
    ```
2. **下载并编译：**```bash
    cd /tmp
    # 下载源码 (以 3.28.3 为例)
    wget https://cmake.org/files/v3.28/cmake-3.28.3.tar.gz
    tar -zxvf cmake-3.28.3.tar.gz
    cd cmake-3.28.3
    
    # 配置、编译、安装
    ./bootstrap
    make -j$(nproc)  # 使用多核编译加速
    sudo make install
    
    ```

### 💡 总结建议

- **首选方法一**：它不会干扰系统自带的 Python 或其他工具对旧版 CMake 的依赖，且升级过程秒级完成。
- **安装完 OpenClaw 后**：如果遇到权限问题，记得给 OpenClaw 的相关目录赋予权限，或者使用 `sudo` 运行。