---
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-hant/docs/%e5%9c%a8-ubuntu-24-04-%e4%b8%8a%e5%98%97%e8%a9%a6%e5%ae%89%e8%a3%9d-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）
- Gateway 連接埠：18789（loopback）

模型與搜尋後端

- GPUStack + vLLM 0.17.1
- Qwen2.5-14B-Instruct
- SearXNG（自建）
- Custom Provider（OpenAI 相容）

**與 Windows 的主要差異**
在 Ubuntu 上，僅靠官方安裝程式（`install.sh`）即可完成從 Node.js 設定到 OpenClaw 安裝與導覽設定的所有步驟。
由於系統具備 systemd，Gateway 服務註冊也會自動完成。

## 安裝步驟

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 金鑰提供方式：**立即貼上 API 金鑰**
   - 端點相容性：`OpenAI-compatible`
   - Model ID：在 GPUStack 上執行的模型名稱
   - Channel：**暫時略過**
   - 技能相依套件：**暫時略過**
   - 網頁搜尋：**SearXNG Search** → 輸入 URL
   - Hooks：僅啟用 `session-memory`
   導覽設定完成後，**系統會自動安裝並啟動 systemd 服務**。
4. ### 修正 context 上限與模型設定（重要）
   若在導覽設定完成後立即開始對話，可能會出現 `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. ### 確認 Gateway 啟動狀態
   ```
   openclaw gateway status
   systemctl --user is-enabled openclaw-gateway.service
   ```
   若顯示 `enabled`，代表 Gateway 會在作業系統開機時自動啟動。

## 遠端存取設定（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」按鈕即可開啟主控台。

**核准具持久性**
裝置一旦核准後，即使重新啟動 Gateway 也不需要再次核准。
若清除瀏覽器快取或改用其他瀏覽器，則會被視為新裝置，需要重新核准。

## 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 問題
- Gateway 自動註冊為 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** 可避免
在開始對話後立刻發生 context 溢位。

**三種環境的總結**
安裝難易度排名為 **Ubuntu 24.04 << Windows 11 < Windows Server 2019**。
若可以選擇 Linux 環境，強烈建議使用 Ubuntu。本文所述程序，係以 2026 年 4 月當時的 OpenClaw v2026.4.10、vLLM 0.17.1 及 GPUStack 為基準。
若版本有所變更，行為可能會有所不同。