---
title: 在 Ubuntu 24.04 上尝试安装 OpenClaw
description: "基础设施 / 自托管 AI 智能体 # 在 Ubuntu 24.04 上安装 OpenClaw 继此前在 Windows Server 2019 和 Windows 11 上的验证之后，本次我们又在 Ubuntu 24.04 上验证了 OpenClaw 的安装。 Linux 原生环境获得官方支持，相比 Windows 环境要简单得多。 不过，其中存在一个**需要为远程仪表盘访问进行设备配对审批的坑**。 我们将包含这些步骤在内的完整记录公开如下。 OpenClaw Ubuntu 24.04 Linux nginx HTTPS GPUStack**与前几篇文章的关系** 本文是“Windows Server 2019”和“Windows…"
url: "https://bestnetllc.co.jp/zh-hans/docs/%e5%9c%a8-ubuntu-24-04-%e4%b8%8a%e5%b0%9d%e8%af%95%e5%ae%89%e8%a3%85-openclaw/"
updated: "2026-06-08"
category: Tech Blog
---

# 在 Ubuntu 24.04 上尝试安装 OpenClaw

基础设施 / 自托管 AI 智能体

# 在 Ubuntu 24.04 上安装 OpenClaw

继此前在 Windows Server 2019 和 Windows 11 上的验证之后，本次我们又在 Ubuntu 24.04 上验证了 OpenClaw 的安装。
Linux 原生环境获得官方支持，相比 Windows 环境要简单得多。
不过，其中存在一个**需要为远程仪表盘访问进行设备配对审批的坑**。
我们将包含这些步骤在内的完整记录公开如下。

OpenClaw
Ubuntu 24.04
Linux
nginx
HTTPS
GPUStack**与前几篇文章的关系**
本文是“Windows Server 2019”和“Windows 11”版 OpenClaw 安装记录的后续篇。
在 Windows 环境中造成困扰的 PATH 问题、npm 错误以及 NODE_OPTIONS 问题，在 Ubuntu 上完全没有出现。

## 环境配置

OpenClaw 主机

- Ubuntu 24.04 LTS
- OpenClaw v2026.4.10（npm 安装）
- Node.js v22.22.2（由安装脚本自动配置）
- nginx 反向代理（443/HTTPS）
- 网关端口：18789（回环地址）

模型与搜索后端

- GPUStack + vLLM 0.17.1
- Qwen2.5-14B-Instruct
- SearXNG（本地部署）
- Custom Provider（OpenAI 兼容）

**与 Windows 的主要差异**
在 Ubuntu 上，仅凭官方安装脚本（`install.sh`）即可完成从 Node.js 配置到 OpenClaw 安装及引导设置的全部工作。
由于系统提供 systemd，网关服务的注册也会自动完成。

## 安装步骤

1. ### 更新软件包并安装所需工具
   ```
   sudo apt update && sudo apt upgrade -y
   sudo apt install -y curl git
   ```
2. ### 安装 OpenClaw
   运行官方安装脚本，Node.js 的配置也会自动完成。
   ```
   curl -fsSL https://openclaw.ai/install.sh | bash
   ```
   安装脚本会自动执行以下操作：
   - 安装 Node.js v22（通过 NodeSource）
   - 安装构建工具（make / g++ / cmake）
   - 安装 OpenClaw npm 软件包
   - 启动引导向导
   **与 Windows 的差异**
   在 Ubuntu 上，npm 安装不会出现 MODULE_NOT_FOUND 错误。
   也无需切换到 pnpm，官方安装脚本可以直接正常使用。
3. ### 引导设置
   安装完成后向导会自动启动，配置项如下：
   - 安全警告：选择 `Yes` 继续
   - 设置模式：`QuickStart`
   - 模型提供商：**Custom Provider**
   - Base URL：`http://<GPUStack IP>/v1`
   - API 密钥提供方式：**Paste API key now**
   - 接口兼容性：`OpenAI-compatible`
   - 模型 ID：在 GPUStack 上运行的模型名称
   - 消息渠道：**Skip for now**
   - 技能依赖：**Skip for now**
   - 网络搜索：**SearXNG Search** → 输入 URL
   - Hooks：仅启用 `session-memory`
   引导完成后，**系统会自动安装并启动 systemd 服务**。
4. ### 修正上下文限制与模型配置（重要）
   如果在引导完成后立即开始聊天，可能会出现 `Context limit exceeded` 错误。
   **安装完成后立即进行以下设置即可避免该问题。**
   ### 方法①：从仪表盘 UI 配置（推荐）
   仪表盘左侧菜单 **“AI and Agents”** →
   **“Models” 标签页** → 打开相应模型的 **“Compat”** 部分，
   设置以下数值后点击 **“Save”**。
   - **Context Tokens**：`65536`
   - **Context Window**：`65536`
     [![](https://bestnetllc.co.jp/wp-content/uploads/2026/04/annotated_image1.png)](https://bestnetllc.co.jp/wp-content/uploads/2026/04/annotated_image1.png)
   - **Max Tokens**：`4096`（保持默认）
     [![](https://bestnetllc.co.jp/wp-content/uploads/2026/04/annotated_image2.png)](https://bestnetllc.co.jp/wp-content/uploads/2026/04/annotated_image2.png)
   ### 方法②：从命令行配置
   ```
   # Increase compaction buffer
   openclaw config set agents.defaults.compaction.reserveTokensFloor 20000
   # Manually fix contextWindow (change provider name to match your environment)
   python3 - << 'EOF'
   import json, os
   path = os.path.expanduser("~/.openclaw/openclaw.json")
   with open(path) as f:
       c = json.load(f)
   for k, v in c["models"]["providers"].items():
       for m in v.get("models", []):
           m["contextWindow"] = 65536
           m["maxTokens"] = 4096
   with open(path, "w") as f:
       json.dump(c, f, indent=2, ensure_ascii=False)
   print("Update complete")
   EOF
   openclaw gateway restart
   ```
   **通过 UI 配置更可靠**
   在仪表盘中设置会立即生效，可避免配置错误。
   通过 CLI 配置后，必须始终执行 `openclaw gateway restart`。
5. ### 验证网关启动状态
   ```
   openclaw gateway status
   systemctl --user is-enabled openclaw-gateway.service
   ```
   如果显示 `enabled`，则网关会在系统启动时自动运行。

## 远程访问配置（nginx + 自签名证书）

如果想从网络上的其他计算机访问仪表盘，需要将 nginx 配置为反向代理。
由于使用了 WebSocket，nginx 配置中需要转发 Upgrade 头。

1. ### 安装 nginx 并生成自签名证书
   ```
   sudo apt install -y nginx
   # Generate self-signed certificate (valid for 10 years)
   sudo mkdir -p /etc/nginx/ssl
   sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 
     -keyout /etc/nginx/ssl/openclaw.key 
     -out /etc/nginx/ssl/openclaw.crt 
     -subj "/CN=openclaw.local"
   ```
2. ### 创建 nginx 配置文件
   ```
   sudo tee /etc/nginx/sites-available/openclaw << 'EOF'
   server {
       listen 443 ssl;
       server_name _;
       ssl_certificate     /etc/nginx/ssl/openclaw.crt;
       ssl_certificate_key /etc/nginx/ssl/openclaw.key;
       location / {
           proxy_pass http://127.0.0.1:18789;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_read_timeout 86400;
       }
   }
   server {
       listen 80;
       return 301 https://$host$request_uri;
   }
   EOF
   sudo ln -sf /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
   sudo rm -f /etc/nginx/sites-enabled/default
   sudo nginx -t && sudo systemctl restart nginx
   sudo systemctl enable nginx
   ```
3. ### 修改 OpenClaw 配置
   ```
   # Allow connections from non-localhost
   openclaw config set gateway.controlUi.allowInsecureAuth true
   # Allow origin of access source
   openclaw config set gateway.controlUi.allowedOrigins '["*"]'
   openclaw gateway restart
   ```
4. ### 开放防火墙
   ```
   sudo ufw allow 443/tcp
   sudo ufw allow 80/tcp
   ```

## 远程访问的设备配对审批

从其他计算机访问仪表盘时，会显示 **pairing required** 错误。
这是 OpenClaw 的安全功能，首次访问需要管理员批准。
批准后之后就不再需要了。

**常见错误**
用于渠道（Telegram、Discord 等）配对的 `openclaw pairing` 命令**在此不适用**。
仪表盘设备批准需要使用 `openclaw devices` 命令。

1. ### 从浏览器访问仪表盘
   在浏览器中打开包含 token 的 URL，并在服务器端进行确认。
   ```
   openclaw dashboard
   # Open the displayed URL (#token=...) in a browser
   ```
   浏览器会显示 `pairing required`，请在此状态下继续下一步。
2. ### 查看待批准列表并批准
   ```
   # List devices waiting for pairing
   openclaw devices list
   # Approve all displayed Request IDs
   openclaw devices approve <Request ID>
   ```
   如果有多个待批准的请求，请全部批准。
3. ### 在浏览器中重新连接
   批准后，在浏览器中点击“Connect”按钮即可打开仪表盘。

**批准状态会持久保存**
设备一旦获批，即使网关重启也无需再次批准。
清除浏览器缓存或更换浏览器会被视为新设备，需要重新批准。

## GPUStack 配置

在 GPUStack 管理界面中，将以下内容添加到模型的后端参数中，然后重启模型。

```
--max-model-len 32768
--generation-config vllm
--enable-auto-tool-choice
--tool-call-parser hermes
```

## 与 Windows 环境的对比

在 Ubuntu 上变得更简单的地方

- 仅凭 `install.sh` 即可自动完成从 Node.js 开始的全部配置
- 不会出现 MODULE_NOT_FOUND 错误（无需 pnpm）
- 没有 PATH 问题，也没有 NODE_OPTIONS 问题
- 网关会自动注册为 systemd 服务
- 使用 nginx 可轻松配置反向代理

在 Ubuntu 上仍需手动完成的工作

- 手动配置 contextWindow / compaction
- 配置 GPUStack 后端参数

## 操作验证清单

- 显示 `openclaw --version`
- `systemctl --user is-enabled openclaw-gateway.service` 显示 `enabled`
- `openclaw gateway status` 显示 `RPC probe: ok`
- 从另一台计算机的浏览器访问 `https://<server IP>`
- 使用 `openclaw devices approve` 完成设备批准
- 在 `main` 会话中能返回聊天响应
- 会话界面 TOKENS 显示 `xxxxx / 32768`
- SearXNG 搜索功能正常

## 总结

在 Ubuntu 24.04 上安装 OpenClaw，比 Windows 环境要简单得多。
只需运行安装脚本，即可完成从 Node.js 配置到服务注册的全部工作。

唯一的坑是**远程仪表盘访问所需的设备配对**。
请注意使用 `openclaw devices`，而不是（用于渠道的）`openclaw pairing`。
此外，**安装完成后立即配置 contextWindow 与 compaction 设置**，
可以避免开始对话后立刻出现上下文溢出。

**三种环境总结**
安装难度排名为 **Ubuntu 24.04 << Windows 11 < Windows Server 2019**。
如果可以选择 Linux 环境，强烈推荐使用 Ubuntu。本文所述步骤基于 2026 年 4 月时的 OpenClaw v2026.4.10、vLLM 0.17.1 及 GPUStack 版本。
若版本发生变化，实际行为可能有所不同。