Deploying OpenClaw on Ubuntu and Configuring the API

发表于 阅读次数： 本文字数： 8.2k 阅读时长 ≈ 15 分钟

Overview

I hadn’t paid much attention to OpenClaw before, mainly because the API consumption is relatively high and costly. This time I received a free Unicom Coding Plan Pro along with a 2-core 4GB cloud server, so I decided to give it a try.
This article first covers how to install OpenClaw on an Ubuntu cloud server. Usage guides and further details will be written when time permits.

  1. OS: Ubuntu 22.04 Server
  2. OpenClaw version: 2026.2.26
  3. Cloud server: 2-core 4GB RAM
  4. User: root

Installation

Install OpenClaw

I am using a cloud server with a clean OS — no software pre-installed.
Installing OpenClaw is actually very simple. Run the following one-liner to install it:

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

The installation script will automatically install Node, OpenClaw, and other dependencies. Select “Yes” for all prompts in the interface.

After installation, the Gateway will fail to start (don’t worry — once we complete the configuration below, we just need to restart the Gateway). At the end, the following information will appear on the screen:

1
2
3
4
5
6
7
8
9
10
11
12
🦞 OpenClaw 2026.2.26 (bc50708) — Your task has been queued; your dignity has been deprecated.

Dashboard URL: http://127.0.0.1:18789/#token=85xxxxxxxxxxxxd9c6b036328fe00d04fd3c98
Copy to clipboard unavailable.
No GUI detected. Open from your computer:
ssh -N -L 18789:127.0.0.1:18789 root@192.168.0.167
Then open:
http://localhost:18789/
http://localhost:18789/#token=85xxxxxxxxxxxxd9c6b036328fe00d04fd3c98
Docs:
https://docs.openclaw.ai/gateway/remote
https://docs.openclaw.ai/web/control-ui

At this point, you cannot access http://localhost:18789/#token=85xxxxxxxxxxxxd9c6b036328fe00d04fd3c98 normally.

No worries — just follow the configuration steps below.

Installation screen 1

Installation screen 2

Install Nginx (Skip this step if you are only using it locally with a GUI)

Run the following command:

1
apt install -y nginx

If a selection prompt appears, simply confirm and proceed.

Navigate to /etc/nginx/, find the nginx.conf file, and update it as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

events {
	worker_connections 768;
	# multi_accept on;
}

http {

	##
	# Basic Settings
	##

	sendfile on;
	tcp_nopush on;
	types_hash_max_size 2048;
	server_tokens off;

	# server_names_hash_bucket_size 64;
	# server_name_in_redirect off;

	include /etc/nginx/mime.types;
	default_type application/octet-stream;

	##
	# SSL Settings
	##

	ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3; # Dropping SSLv3, ref: POODLE
	ssl_prefer_server_ciphers on;

	##
	# Logging Settings
	##

	access_log /var/log/nginx/access.log;
	error_log /var/log/nginx/error.log;

	##
	# Gzip Settings
	##

	gzip on;

	# gzip_vary on;
	# gzip_proxied any;
	# gzip_comp_level 6;
	# gzip_buffers 16 8k;
	# gzip_http_version 1.1;
	# gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

	##
	# Virtual Host Configs
	##

	include /etc/nginx/conf.d/*.conf;
	include /etc/nginx/sites-enabled/*;

	server {
		listen 18790;
		server_name your-domain.com;  # Replace with your domain name or IP

		location / {
			proxy_pass http://127.0.0.1:18789;

			# Required header forwarding
			proxy_set_header Host $host;
			proxy_set_header X-Real-IP $remote_addr;
			proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
			proxy_set_header X-Forwarded-Proto $scheme;

			# WebSocket support (if OpenClaw uses WS)
			proxy_http_version 1.1;
			proxy_set_header Upgrade $http_upgrade;
			proxy_set_header Connection "upgrade";

			# Timeout and buffer optimization (optional)
			proxy_connect_timeout 60s;
			proxy_send_timeout 60s;
			proxy_read_timeout 60s;
			proxy_buffering on;
			proxy_buffer_size 4k;
			proxy_buffers 8 4k;
		}

		# Health check endpoint (optional)
		location /health {
			access_log off;
			proxy_pass http://127.0.0.1:18789/health;
		}
	}
}

Save the file and run the following command:

1
nginx -s reload

Start the Gateway

Run the following commands:

1
2
openclaw config set gateway.mode local
openclaw gateway restart

local

If the console shows no failure messages, the Gateway has started successfully. After configuring the firewall, you can access the UI in your browser, for example: http://:18790/#token=85xxxxxxxxxxxxd9c6b036328fe00d04fd3c98

At this point the UI may still show some errors — proceed to the next step.

Configure OpenClaw

Once you can access the UI, it is still not usable yet — you need to modify the OpenClaw configuration file located in the /root/.openclaw directory.

Below I provide the complete configuration that you can use directly. Replace the token, allowedOrigins, apiKey, and other values with your own settings. I am using the free Unicom Coding Plan.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
{
  "meta": {
    "lastTouchedVersion": "2026.2.26",
    "lastTouchedAt": "2026-02-28T13:04:18.321Z"
  },
  "wizard": {
    "lastRunAt": "2026-02-28T11:48:10.150Z",
    "lastRunVersion": "2026.2.26",
    "lastRunCommand": "doctor",
    "lastRunMode": "local"
  },
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "model": {
        "primary": "Unicom/MiniMax-M2.5"
      },
      "models": {
        "Unicom/MiniMax-M2.5": {}
      }
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "Keep the original Token"
    },
    "controlUi": {
      "allowedOrigins": [
        "http://60.13.54.190:18790",
        "http://192.168.0.167:18790",
        "http://192.168.0.167:18789",
        "http://127.0.0.1:18789"
      ],
      "allowInsecureAuth": true,
      "dangerouslyDisableDeviceAuth": true
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "Unicom": {
        "baseUrl": "https://aigw-gzgy2.cucloud.cn:8443/v1",
        "apiKey": "sk-sp-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "api": "openai-completions",
        "models": [
          {
            "id": "MiniMax-M2.5",
            "name": "MiniMax-M2.5",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 128000,
            "maxTokens": 32000
          },
          {
            "id": "Qwen3.5-397B-A17B",
            "name": "Qwen3.5-397B-A17B",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 128000,
            "maxTokens": 32000
          }
        ]
      }
    }
  }
}

After making your edits, first back up the original openclaw.json file, then replace it with the updated file and restart the Gateway:

1
openclaw gateway restart

Once started successfully, you can access the UI in your browser, for example: http://:18790/#token=85xxxxxxxxxxxxd9c6b036328fe00d04fd3c98

Everything should now be working correctly in the UI!

UI

Troubleshooting

Issue 1: Gateway start blocked: set gateway.mode=local (current: unset) or pass –allow-unconfigured

Solution:

1
2
openclaw config set gateway.mode local
openclaw gateway restart

Issue 2: origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)

Solution:
Modify the "gateway" section in openclaw.json, add the "controlUi" block, and restart the Gateway:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
"gateway": {
  "mode": "local",
  "auth": {
    "mode": "token",
    "token": "85xxxxxxxxd95d0d9c6b0xxxxxxxx04fd3c98"
  },
  "controlUi": {
    "allowedOrigins": [
      "http://60.13.54.190:18790",
      "http://192.168.0.167:18790",
      "http://192.168.0.167:18789",
      "http://127.0.0.1:18789"
    ],
    "allowInsecureAuth": true,
    "dangerouslyDisableDeviceAuth": true
  }
}