Skip to main content

Install OpenClaw on Ubuntu

· 9 min read

This guide walks through installing Node.js 22, OpenClaw, and configuring the Alibaba Cloud Bailian (Qwen) model on Ubuntu.

1. Requirements​

  • OS: Ubuntu (20.04 / 22.04 LTS recommended)
  • Node.js: ≥ 22.12.0 (required by OpenClaw)
  • Memory: ≥ 4GB recommended
  • Network: Access to Alibaba Bailian API (dashscope.aliyuncs.com)

2. Install Node.js 22​

# Update and install dependencies
sudo apt update && sudo apt install -y curl

# Add Node.js 22 repo and install
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs build-essential

# Verify
node -v   # Should show v22.x.x
npm -v

3. Install OpenClaw​

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

The script will detect/install Node.js and install OpenClaw. After installation, run:

openclaw onboard --install-daemon

Complete the wizard: workspace, security, channels, etc. You can skip models for now and configure Bailian later.

Install via npm (when Node 22 is already installed)​

sudo npm install -g openclaw@latest
openclaw onboard --install-daemon

4. Get Alibaba Bailian API Key​

  1. Sign in at Alibaba Bailian (Model Studio) (default region: Beijing).
  2. Go to Key Management and click Create API Key.
  3. Copy the API Key (only visible at creation; store it safely).

New users can claim free trial credits on the Bailian platform.

5. Configure Alibaba Bailian (Qwen) in OpenClaw​

Bailian exposes an OpenAI-compatible API; OpenClaw can use it via baseUrl and apiKey.

5.1 Edit OpenClaw config​

Config path: ~/.openclaw/openclaw.json.

Add a Bailian provider under models.providers (or merge into existing JSON), for example:

{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "YOUR_DASHSCOPE_API_KEY",
        "api": "openai-completions",
        "models": [
          { "id": "qwen-plus", "name": "Qwen Plus" },
          { "id": "qwen-turbo", "name": "Qwen Turbo" },
          { "id": "qwen-max", "name": "Qwen Max" },
          { "id": "qwen3-max", "name": "Qwen3 Max" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "bailian/qwen-plus" },
      "models": {
        "bailian/qwen-plus": { "alias": "Qwen" },
        "bailian/qwen-turbo": {},
        "bailian/qwen-max": {},
        "bailian/qwen3-max": {}
      }
    }
  }
}

Notes:

  • baseUrl (choose by region): Beijing: https://dashscope.aliyuncs.com/compatible-mode/v1; Singapore: https://dashscope-intl.aliyuncs.com/compatible-mode/v1; Virginia: https://dashscope-us.aliyuncs.com/compatible-mode/v1
  • apiKey: Replace with your Bailian API Key. If DASHSCOPE_API_KEY is set, some versions allow "dashscope" here to read from env.
  • agents.defaults.model.primary: Default model, e.g. bailian/qwen-plus.
  • Model IDs follow Bailian docs; common ones: qwen-turbo, qwen-plus, qwen-max, qwen3-max.

If you already have other providers (e.g. qwen-portal), keep them and add bailian under providers.

5.2 Set default model via CLI (optional)​

openclaw models set primary bailian/qwen-plus
openclaw models list

6. Remote access​

OpenClaw does not allow plaintext ws:// to non-loopback addresses (SECURITY ERROR and gateway exit). For remote access, choose one:

  • Recommended: Option A — Keep gateway bind: "loopback" and use SSH tunnel from your machine (no need to expose 18789; most secure).
  • Option B — If you must use a public IP, put HTTPS/WSS in front (e.g. Nginx/Caddy or Tailscale), use wss://, then you may set bind: "lan".

6.1 Option A: loopback + SSH tunnel (recommended)​

Gateway listens only on localhost; you access it remotely via SSH port forwarding. No need to open 18789 or expose it.

（1）Edit ~/.openclaw/openclaw.json — in the gateway section ensure:

"gateway": {
  "port": 18789,
  "mode": "local",
  "bind": "loopback",
  "controlUi": {
    "allowedOrigins": [
      "http://127.0.0.1:18789",
      "http://localhost:18789"
    ]
  },
  "auth": {
    "mode": "token",
    "token": "your-access-token"
  }
}

Note: mode: "local" is for local/tunnel access. If set to "remote", OpenClaw may require remote config (e.g. WSS) before starting, or the gateway may exit with "Gateway start blocked" (see FAQ).

（2）Start the gateway on the server

openclaw gateway start
# or: systemctl --user restart openclaw-gateway.service

（3）On your own machine, create an SSH tunnel

ssh -N -L 18789:127.0.0.1:18789 user@YOUR_SERVER_IP

Keep this terminal open. Then open http://localhost:18789 in the browser (or with token: http://localhost:18789/?token=your-token).
Note: Token must be sent as query ?token=xxx, not #token=xxx (hash is client-side only). Traffic is over SSH, so you don’t need to open 18789 in the firewall.

6.2 Option B: Public IP (requires HTTPS/WSS)​

If you need to reach the gateway at http://<public-IP>:18789, OpenClaw requires wss://, not plain ws://. So:

  1. Use Nginx/Caddy (or similar) to serve HTTPS on 443 and proxy WebSocket to http://127.0.0.1:18789.
  2. Keep gateway bind: "loopback" and only reach it via the reverse proxy.
  3. Use https://your-domain / wss://your-domain in the browser and CLI, not http://IP:18789.

You can also use Tailscale Serve/Funnel for HTTPS remote access. See official docs for reverse proxy details.

If you had bind: "lan" and see SECURITY ERROR, switch back to bind: "loopback" and use Option A or configure WSS first.

6.3 CLI config (optional)​

# Local mode + loopback (recommended with SSH tunnel)
openclaw config set gateway.mode "local"
openclaw config set gateway.bind "loopback"

6.4 Restart gateway to apply config​

systemctl --user restart openclaw-gateway.service
# or
openclaw gateway start

6.5 Access summary​

  • Local: http://localhost:18789 or http://127.0.0.1:18789
  • Remote (Option A): Run ssh -N -L 18789:127.0.0.1:18789 user@SERVER_IP, then open http://localhost:18789 (use ?token=your-token if needed; do not use #token=...)
  • Remote (Option B): Use your configured HTTPS URL (e.g. https://your-domain)

Do not use http://public-IP:18789 directly: OpenClaw blocks plain WebSocket to non-loopback; with loopback the gateway does not listen on the public interface. Use Option A (SSH tunnel) or Option B (HTTPS reverse proxy).

7. Ports and firewall​

  • Option A (SSH tunnel): No need to open 18789; only SSH (22) must be reachable.
  • Option B (HTTPS): Open 443 (and 80 if you redirect HTTP to HTTPS); gateway still listens only on localhost; do not expose 18789.

Open 80 or others only if you need callbacks (e.g. for some channels).

8. Start and verify​

# If daemon is installed, start the gateway
openclaw gateway start

# Or run as service (depending on your onboard choice)
  • Local: http://localhost:18789
  • Remote: Establish SSH tunnel (Section 6) then http://localhost:18789, or use your HTTPS URL

In the console Models or chat page, select Qwen (or the configured alias) and send a message; a normal reply means Bailian is connected.

9. Common commands​

CommandDescription
openclaw doctorCheck environment and config
openclaw models listList configured models
openclaw models set primary <provider/model>Set default model
openclaw config get models.providers.bailian.baseUrlInspect provider config
openclaw gateway startStart gateway

10. FAQ​

  1. Node version too low
    Run node -v. If below 22, install Node 22 via NodeSource (Section 2) and reinstall OpenClaw.

  2. Bailian 401 / call failure

    • Check apiKey is correct and not expired.
    • Ensure the model (e.g. qwen-plus) is enabled in Bailian console.
    • If using env var, run source ~/.bashrc and confirm echo $DASHSCOPE_API_KEY in the current shell.

  3. Cannot open console

    • Confirm openclaw gateway start is running.
    • Check firewall/security group for 18789 if you expect direct access (Option B).

  4. Page loads but "disconnected from gateway" or no connection

    • With SSH tunnel: ensure the tunnel is up and the browser uses http://localhost:18789.
    • Check gateway.controlUi.allowedOrigins includes your access Origin (for local: http://127.0.0.1:18789, http://localhost:18789).
    • Restart gateway after config changes: systemctl --user restart openclaw-gateway.service or run openclaw gateway start again.

  5. 502 Bad Gateway on remote

    • With SSH tunnel: Often gateway not running or tunnel not active. On server run openclaw gateway status (Runtime running); on your machine ensure the tunnel process is running and the browser uses http://localhost:18789 only.
    • With Nginx/reverse proxy: 502 means the proxy cannot reach http://127.0.0.1:18789. First: (1) On server run curl -I http://127.0.0.1:18789/ (expect 200 or 3xx). (2) Proxy must forward WebSocket (Upgrade, Connection: upgrade, proxy_http_version 1.1). Example for Nginx: 
      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;
      }
      (3) Reload proxy and restart gateway: systemctl --user restart openclaw-gateway.service.

  6. SECURITY ERROR: Gateway URL uses plaintext ws:// to a non-loopback address

    • OpenClaw disallows plain WebSocket to non-loopback and may exit.
    • Fix: Set gateway.bind to "loopback" and use SSH tunnel (Section 6 Option A), or configure HTTPS/WSS first then use bind: "lan".
    • You can run openclaw doctor --fix or see official docs.

  7. Gateway start blocked: set gateway.mode=local (current: remote) or pass --allow-unconfigured

    • When gateway.mode is "remote", OpenClaw may require remote config (e.g. WSS) before starting; otherwise it exits (exit 1).
    • Fix: For loopback + SSH tunnel, set gateway.mode to "local": 
      openclaw config set gateway.mode "local"
      systemctl --user restart openclaw-gateway.service
    • To keep mode: "remote", you can add --allow-unconfigured to the gateway command in the systemd unit (edit ~/.config/systemd/user/openclaw-gateway.service).

  8. Gateway exits right after start (Runtime: stopped, last exit 1 / RPC probe: 1006)

    • Check logs: 
      cat /tmp/openclaw/openclaw-YYYY-MM-DD.log
      journalctl --user -u openclaw-gateway.service -n 100 --no-pager
    • Common causes: gateway.mode=remote not fully configured (see above), Node < 22, port in use, invalid JSON or field in config, workspace/permission issues.
    • Run openclaw doctor and try foreground start: openclaw gateway --port 18789 to see errors.

  9. Region for servers in China
    For Beijing region, use baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1.

  10. No API key found for provider "anthropic"

  • The agent is trying to use Anthropic (Claude) but no API key is set. If you only use Qwen, configure the agent to use Bailian.
  • Steps (on server): (1) Ensure ~/.openclaw/openclaw.json has correct models and agents.defaults.model.primary (e.g. bailian/qwen-plus). (2) Add auth for the agent: 
    openclaw agents add main
    Configure API key for bailian (or dashscope); if DASHSCOPE_API_KEY is set, check docs for using env. (3) Optionally restrict the agent to Qwen only so it doesn’t fall back to anthropic.
  • If the error says to copy auth from main agent: copy the main agent’s auth file to the failing agent’s dir (only when main already has Bailian configured): 
    cp ~/.openclaw/agents/main/agent/auth-profiles.json ~/.openclaw/agents/<agentDir>/auth-profiles.json

11. References​