← Back to Free Tools

Install OpenClaw on a VPS

Complete guide. From a blank server to a running AI agent with web dashboard.

Prerequisites

1. Get a VPS

If you don't have a server yet, grab one from Contabo ($6.99/mo for 4 CPU, 8GB RAM) or any provider. You need Ubuntu 22.04 or 24.04.

SSH into your server:

Update packages first:

2. Install Node.js

OpenClaw requires Node.js 20+.

3. Install OpenClaw

4. Configure OpenClaw

OpenClaw has a guided setup. Run it and configure each section one at a time:

You can only select one section per run. Run openclaw configure again for each section.

Round 1: Model (most important)

Select Model → choose your AI provider and paste your API key.

Round 2: Gateway

Select Gateway → set these options:

Setting	Choose
Gateway port	18789 (default)
Bind mode	LAN (All interfaces)
Auth	Token (default)
Tailscale	Off
Token source	Generate/store plaintext token (default)

Round 3+ (optional): Workspace, Channels, Skills

Run openclaw configure again for each section you want to set up. Defaults are fine for most.

Enable shell command execution (critical)

By default, the agent may not be able to run shell commands. You need to enable tool execution so the agent can use gog, run scripts, and interact with the system.

Open the config file:

Find or add the "tools" section inside the top-level JSON object. Add this block (merge with existing config if needed):

Save the file (Ctrl+O, Enter, Ctrl+X). The gateway will pick up the changes on next restart.

Install useful tools on the VPS

The agent can use any CLI tool installed on the server. Install these common ones:

Authenticate GitHub CLI (optional, if your agent needs repo access):

Install OpenClaw skills

Skills teach the agent how to use specific tools. Install them with clawhub:

Playwright requires extra setup — it needs Chromium and system dependencies:

Playwright environment variables:

Variable	Default	Description
HEADLESS	true	Run browser without display (must be true on VPS)
SAVE_HTML	false	Save page HTML alongside screenshots
WAIT_TIME	5000	Milliseconds to wait for page to load
SCREENSHOT_PATH	./screenshot.png	Where to save screenshots
USER_AGENT	default	Custom browser user agent string

After installing skills, restart the gateway: openclaw gateway --force

Install ClawFlows (automated workflows)

ClawFlows adds 100+ pre-built workflows to your agent — morning briefings, email summaries, calendar checks, and more.

When asked to enable the essentials pack, say Y. It enables:

• send-morning-inspiration — uplifting quote to start your day
• send-morning-briefing — weather, calendar, priorities at 7am
• check-email — inbox summary with categorization
• check-calendar — 48-hour radar with conflict detection

After install, open a new terminal tab or run:

Useful commands:

Supported providers

Provider	Env Variable	Cost
OpenRouter	OPENROUTER_API_KEY	Pay per use, cheapest
OpenAI	OPENAI_API_KEY	Pay per use
Anthropic	ANTHROPIC_API_KEY	Pay per use
Ollama (local)	OLLAMA_BASE_URL	Free (runs on your hardware)

5. Set up nginx + Cloudflare (HTTPS)

The web UI requires HTTPS for device pairing. Set this up before starting the gateway.

5a. Add DNS record in Cloudflare

In your Cloudflare dashboard, add an A record:

Field	Value
Type	A
Name	agent1 (or any subdomain)
Content	YOUR_VPS_IP
Proxy	ON (orange cloud)

5b. Cloudflare settings

In Cloudflare dashboard, configure these settings:

Setting	Location	Value
SSL/TLS mode	SSL/TLS → Overview	Full
WebSockets	Network	ON
Rocket Loader	Speed → Optimization	OFF
Email Obfuscation	Scrape Shield	OFF
Auto Minify JS	Speed → Optimization	OFF

5c. Install and configure nginx

Replace the entire file with (change agent1.yourdomain.com to your subdomain):

Save (Ctrl+O, Enter, Ctrl+X) and test:

5d. Allow the domain in OpenClaw

6. Start the Gateway

You should see output like:

7. Pair the Web UI

Pairing is a two-step process: first you submit the token in the browser, then you approve the device from the VPS command line.

7a. Get your token

In your second SSH session:

Copy the token value (the long hex string).

7b. Submit the token in the browser

Open https://agent1.yourdomain.com in your browser. You'll see the Gateway Dashboard with these fields:

• WebSocket URL: wss://agent1.yourdomain.com (should be pre-filled)
• Gateway Token: paste your token here
• Password: leave blank

Click Connect. It will say "pairing required" — this is expected.

7c. Approve the device from the VPS

Back in your SSH session, list pending pairing requests:

You'll see your browser listed under Pending with a Request ID. Approve it:

7d. Reconnect in the browser

Go back to the browser and click Connect again. It should now connect successfully and show the agent chat interface.

Troubleshooting pairing

"origin not allowed" — Run the allowedOrigins command from Step 5d and restart: openclaw gateway --force

"control ui requires device identity" — You're on HTTP, not HTTPS. Make sure you're using https://.

CSP inline script error in console — Make sure your nginx config includes the proxy_hide_header and add_header lines from Step 5c.

No pending request in openclaw devices list — Make sure you clicked Connect in the browser first, then run the list command immediately.

Fallback: SSH tunnel — If Cloudflare pairing doesn't work, pair via localhost:

Open http://localhost:18789, paste the token, click Connect, then approve via openclaw devices approve.

8. Access via TUI (terminal)

The TUI (Terminal User Interface) is the most reliable way to interact with your agent. No browser needed:

This opens a chat interface directly in your terminal. It has the same capabilities as the web UI.

Useful TUI commands

Command	What it does
/help	Show all commands
/agents	List running agents
/sessions	List active sessions
/model	Change AI model
/think	Toggle thinking mode
/quit	Exit TUI

9. Run as a background service

Keep OpenClaw running even after you close SSH.

Option A: systemd (recommended)

Paste this (update ExecStart path and API key):

Save, then enable and start:

Option B: screen (quick and simple)

10. Connect Gmail, Calendar & Drive

Give your agent access to Google Workspace (Gmail, Calendar, Drive, Contacts) using the gog CLI tool.

10a. Create brewuser (as root)

Homebrew can't run as root on Linux. Create a dedicated user:

10b. Install Homebrew (as brewuser)

Switch to brewuser:

Now install Homebrew (this takes a few minutes):

After it finishes, add brew to your PATH. Run the commands that Homebrew prints at the end. Usually:

10c. Install gog (still as brewuser)

Verify:

10d. Switch back to root

Now add brew to root's PATH so gog is available as root:

Verify gog works as root:

10e. Install gog skill in OpenClaw (as root)

10f. Create Google OAuth credentials (free)

You need OAuth credentials so gog can access Gmail/Calendar. This is 100% free — no billing required.

1. Go to console.cloud.google.com — sign in with the Gmail account your agent will use
2. Create a new project (any name, e.g. "My Agent")
3. Go to APIs & Services → Library — search for and enable Gmail API and Google Calendar API
4. Go to APIs & Services → OAuth consent screen → choose External → fill in app name and your email → Save
5. Under Test users → click + Add Users → add the Gmail address your agent will use
6. Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
7. Application type: Desktop app → name it anything → Create
8. Copy the Client ID and Client Secret

10g. Create credentials file on VPS

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with the values from the previous step.

The output should look like this:

10h. Set up plaintext keyring BEFORE authenticating

10i. Register credentials with gog

10j. Authenticate with Google

This prints a URL like http://127.0.0.1:XXXXX. Since the VPS has no browser, you need an SSH tunnel.

On your local computer (not the VPS), open a new terminal:

Now open http://127.0.0.1:XXXXX in your local browser. Sign in with the Gmail account, click Select all permissions, then Continue.

If gog asks for a keyring password, set one and remember it. You'll need it in the next step.

10k. Set environment variables for OpenClaw

OpenClaw runs gog as a subprocess. It needs these env vars so gog knows which account to use and can unlock the keyring without prompting.

10l. Set timezone

Common timezones: America/New_York, America/Chicago, America/Denver, America/Los_Angeles, Europe/London, Asia/Tokyo

10m. Verify gog works

10n. Restart OpenClaw and test

In the TUI or web UI, tell your agent:

The agent uses gog under the hood. If it works in your terminal, it works for the agent.

Tips & Troubleshooting

"origin not allowed" in browser

Web UI shows "assets not found"

Use the TUI instead — it has the same capabilities: openclaw tui

"unknown command 'start'"

The correct command is gateway, not start:

Port already in use

"aes.KeyUnwrap(): integrity check failed"

Tokens were saved with encryption. Wipe and re-auth with plaintext:

"OAuth credentials not configured"

"OAuth client not found" or "invalid_client"

Check credentials.json has the full "installed" format (see Step 10e). Watch out for extra spaces or line breaks in the client_secret.

Agent can use gog but you can't (or vice versa)

Make sure PYTHON_KEYRING_BACKEND=keyrings.alt.file.PlaintextKeyring is in /etc/environment (for the agent) AND in your .bashrc (for your shell).

Monthly costs

Item	Cost
Contabo VPS (4 CPU, 8GB RAM)	$6.99/mo
OpenRouter API credits	$5-50/mo (usage-based)
OpenClaw	Free (open source)
Google Workspace APIs (Gmail, Calendar)	Free
Cloudflare (SSL + CDN)	Free
Node.js, nginx, Homebrew, gog	Free
Total	~$12-57/mo