Environment Configuration #

Installation Steps #

1. Update packages and install required tools #

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

   Copy to Clipboard

2. Install OpenClaw #

   Run the official installer. Node.js setup is also handled automatically.

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

   Copy to Clipboard

   The installer automatically performs the following:

   • Install Node.js v22 (via NodeSource)
   • Install build tools (make / g++ / cmake)
   • Install OpenClaw npm package
   • Launch the onboarding wizard
   Difference from Windows
   On Ubuntu, npm installation does not produce MODULE_NOT_FOUND errors.
   Switching to pnpm is not necessary. The official installer works as-is.

3. Onboarding #

   The wizard launches automatically after installation completes. The configuration items are as follows:

   • Security warning: Continue with Yes
   • Setup mode: QuickStart
   • Model provider: Custom Provider
   • Base URL: http://<GPUStack IP>/v1
   • API Key provision method: Paste API key now
   • Endpoint compatibility: OpenAI-compatible
   • Model ID: Model name running on GPUStack
   • Channel: Skip for now
   • Skill dependencies: Skip for now
   • Web search: SearXNG Search → Enter URL
   • Hooks: Enable only session-memory

   After onboarding completes, a systemd service is automatically installed and started.

4. Fix context limit and model configuration (important) #

   If you chat immediately after onboarding, a Context limit exceeded error may appear.
   You can avoid this by performing the following settings immediately after installation.

   Method ①: Configure from dashboard UI (recommended) #

   Dashboard left menu “AI and Agents” →
   “Models” tab → Open “Compat” section for the relevant model,
   set the following values and press “Save”.

   • Context Tokens: 65536
   • Context Window: 65536
     
   • Max Tokens: 4096 (keep default)
     

   
   
   

   
   

   Method ②: Configure from command line #

   # 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
   Configuring from UI is more reliable
   Setting from the dashboard immediately reflects changes and prevents configuration mistakes.
   After CLI configuration, openclaw gateway restart is always required.

5. Verify Gateway startup #

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

   Copy to Clipboard

   If enabled is displayed, the Gateway will auto-start on OS boot.

Remote access configuration (nginx + self-signed certificate) #

If you want to use the dashboard from another computer across the network, configure nginx as a reverse proxy.
Since WebSocket is used, the nginx configuration requires Upgrade header forwarding.

1. Set up nginx and self-signed certificate #

   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. Create nginx configuration file #

   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. Change OpenClaw configuration #

   # 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. Open firewall #

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

   Copy to Clipboard

Device pairing approval for remote access #

When accessing the dashboard from another computer, a pairing required error is displayed.
This is an OpenClaw security feature that requires administrator approval on first access.
Once approved, it is not required afterwards.

1. Access dashboard from browser #

   Open the token-included URL in a browser. Verify on the server side.

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

   Copy to Clipboard

   The browser displays pairing required. Proceed to the next step with this state.

2. Check pending list and approve #

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

   Copy to Clipboard

   If there are multiple requests pending, approve all of them.

3. Reconnect from browser #

   After approval, press the “Connect” button in the browser to open the dashboard.

GPUStack configuration #

In the GPUStack management screen, add the following to the model’s backend parameters and restart the model.

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

Comparison with Windows environment #

Operation verification checklist #

• openclaw --version is displayed
• systemctl --user is-enabled openclaw-gateway.service shows enabled
• openclaw gateway status displays RPC probe: ok
• Access https://<server IP> from browser on another computer
• Device approval is completed with openclaw devices approve
• Chat responses are returned in main session
• Session screen TOKENS shows xxxxx / 32768
• SearXNG search functions

Summary #

Installing OpenClaw on Ubuntu 24.04 was significantly simpler compared to Windows environments.
Simply running the installer completes everything from Node.js setup to service registration.

The only pitfall is device pairing for remote dashboard access.
Be careful to use openclaw devices instead of openclaw pairing (for channels).
Also, configuring contextWindow and compaction settings immediately after installation prevents
context overflow immediately after starting conversations.