環境配置 #

安裝步驟 #

1. 更新套件並安裝必要工具 #

   sudo apt update && sudo apt upgrade -y
   sudo apt install -y curl git

   Copy to Clipboard

2. 安裝 OpenClaw #

   執行官方安裝程式。Node.js 的設定也會自動完成。

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

   Copy to Clipboard

   安裝程式會自動執行以下項目：

   • 安裝 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
     
   • Max Tokens：4096（維持預設值）
     

   
   
   

   
   

   方法②：從命令列設定 #

   # 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

   Copy to Clipboard
   從 UI 設定較為可靠
   從主控台設定會立即套用變更，可避免設定錯誤。
   透過 CLI 設定後，務必執行 openclaw gateway restart。

5. 確認 Gateway 啟動狀態 #

   openclaw gateway status
   systemctl --user is-enabled openclaw-gateway.service

   Copy to Clipboard

   若顯示 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"

   Copy to Clipboard

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

   Copy to Clipboard

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

   Copy to Clipboard

4. 開放防火牆 #

   sudo ufw allow 443/tcp
   sudo ufw allow 80/tcp

   Copy to Clipboard

遠端存取的裝置配對核准 #

從其他電腦存取主控台時，會顯示 pairing required 錯誤。
這是 OpenClaw 的安全功能，需要在首次存取時由管理員核准。
核准後，之後便不再需要此步驟。

1. 從瀏覽器存取主控台 #

   在瀏覽器中開啟含有 token 的 URL，並於伺服器端進行驗證。

   openclaw dashboard
   # Open the displayed URL (#token=...) in a browser

   Copy to Clipboard

   瀏覽器會顯示 pairing required。請在此狀態下繼續進行下一步。

2. 檢查待處理清單並核准 #

   # List devices waiting for pairing
   openclaw devices list
   
   # Approve all displayed Request IDs
   openclaw devices approve <Request ID>

   Copy to Clipboard

   若有多筆待處理的請求，請全部核准。

3. 從瀏覽器重新連線 #

   核准後，於瀏覽器按下「Connect」按鈕即可開啟主控台。

GPUStack 設定 #

在 GPUStack 管理畫面中，將以下內容加入模型的後端參數並重新啟動模型。

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

與 Windows 環境的比較 #

運作驗證檢查清單 #

• 顯示 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 溢位。