Set up OpenClaw on Linux

Beginner15 minutes

Audience: Complete beginners -- no terminal experience needed
Duration: 15 minutes (+ optional 30-60 min for Skills)
Difficulty: Beginner
Tested on: Ubuntu 22.04+ LTS, Debian 12, Fedora 39

⚠️ Security note: OpenClaw has access to files and can run commands. This guide works on your Mac/PC — however, we recommend installing it on a VPS or a separate device.

Step 1: Open the Terminal

Ubuntu/Debian Desktop:

Press the Windows key (or Super)
Type: terminal
Click on the icon or press Enter

Alternative: Press Ctrl + Alt + T

A dark screen will open -- that is the Terminal.

Step 2: Install Node.js + NPM

In the Terminal, type:

sudo apt update && sudo apt install -y nodejs npm

(For Fedora/RHEL, type instead: sudo dnf install -y nodejs npm)

Press Enter. It may ask for your password.

This takes about 2-3 minutes.

Step 3: Install OpenClaw

In the Terminal:

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

Press Enter.

Installation takes 3-5 minutes. At the end you will see:

Installation complete!

Step 4: Set Up

In the Terminal:

openclaw onboard

Press Enter.

Note: openclaw onboard is the full first-time setup assistant. To change specific settings later (e.g. channels or model), use openclaw configure.

SCREEN 1: Gateway Location

Where will the Gateway run?
● Local (this machine)
○ Remote (info-only)

Local is already selected. Press Enter.

SCREEN 2: What would you like to configure?

Select sections to configure

● Workspace
○ Model
○ Web tools
○ Gateway
○ Daemon
○ Channels (Link WhatsApp/Telegram/etc)
○ Skills
○ Health check
○ Continue

The cursor (●) is on Workspace. Use the arrow key (↓) to navigate down to Model and press Enter.

SCREEN 3: Choose your AI provider

Model/auth provider

○ OpenAI (ChatGPT)
○ Anthropic (Claude)
○ Google (Gemini)
○ vLLM (Local)
... (many more)

OAuth (free with subscription) vs API Key (paid):

OAuth -- FREE with an existing subscription

OpenAI: ChatGPT subscription (EUR 20/month)
Anthropic (Claude): Claude subscription (EUR 20/month)

You do NOT pay extra -- OpenClaw uses your existing subscription.

API Key -- PAID

Google, others: Costs money per API call

Beginner recommendation:

If you have a ChatGPT subscription: Choose OpenAI

If you have a Claude subscription: Choose Anthropic

Navigate with the arrow keys and press Enter.

SCREEN 4: OAuth Login

Your browser will open.

For OpenAI:

Sign in with your ChatGPT account
Give OpenClaw permission
The browser closes automatically
The Terminal shows: "Auth successful"

SCREEN 2 (back): Further configuration?

Select sections to configure

● Workspace
○ Model (done)
○ Web tools
○ Gateway
○ Daemon
○ Channels (WhatsApp/Telegram/etc)
○ Skills
○ Health check
○ Continue

Options:

Option A: Dashboard only (quick)

Select Continue and press Enter

Option B: Connect WhatsApp (10 min more)

Select Channels and press Enter
See below

Option C: Install Skills (30-60+ min, optional)

Warning: This takes a long time!
Many may fail -- that is NORMAL

(Optional) Connect WhatsApp

If you chose Channels:

SCREEN 3: Channel Status

You will see:

Channel status

Telegram: needs token
WhatsApp (default): not linked <-- We are changing this
Discord: needs token
...

Select WhatsApp and press Enter.

SCREEN 4-7: WhatsApp Setup

(Same as Mac/Windows)

Choose Configure/link
Choose WhatsApp
Scan the QR code with your phone (WhatsApp -> Linked Devices)
Enter your number (+43...)
Done!

SCREEN 2 (back): Continue

Select Continue and press Enter.

Step 5: Open the Dashboard

In the Terminal:

openclaw dashboard

Press Enter.

Your browser will open with:

http://127.0.0.1:18789/

You will see the chat screen!

Step 6: Test Message

Click into the chat screen
Type: "Hello!"
Press Enter

You will get a response!

Step 7: Updates

In the Dashboard:

Update available: v2026.3.13

Click on it. OpenClaw will update (about 30 seconds).

Step 8: Using WhatsApp

If connected:

Open WhatsApp on your phone and type:

"What can you do?"

OpenClaw replies right away!

Step 9: Using Telegram (optional)

If you connected Telegram, there is one important extra step: OpenClaw needs to verify that it trusts you.

Create a Telegram Bot (BotFather)

If you don't have a bot yet:

Open Telegram and search for @BotFather
Type /newbot
Give your bot a name (e.g. "My Assistant")
Give it a username — must end with _bot (e.g. my_assistant_bot)
You'll receive a token (looks like 123456789:ABC-DEF...)
Enter this token during openclaw onboard under Channels → Telegram

Approve the first contact

When you message your bot for the first time, you'll get a pairing code in the terminal. Confirm it:

openclaw pairing approved telegram <CODE>

After that, OpenClaw replies directly in Telegram.

Common Linux Errors and Solutions

Error 1: "curl: command not found"

Solution (Ubuntu/Debian):

sudo apt install curl -y

Solution (Fedora):

sudo dnf install curl -y

Error 2: "command not found: openclaw"

Solution:

source ~/.bashrc

Or: Close the Terminal and reopen it.

Error 3: "Permission denied"

Solution:

bash <(curl -fsSL https://openclaw.ai/install.sh)

Error 4: "localhost:18789 is not working"

Solution (in the Terminal):

openclaw gateway restart

Wait 5 seconds, then try again.

Error 5: "WhatsApp not found" during Channels setup

This is normal.

Try again: openclaw configure -> Channels

Error 6: "Skills installation failed"

This is NORMAL! OpenClaw still works perfectly fine.

Useful Terminal Commands

Gateway \& Status

openclaw dashboard              # Open the Dashboard in your browser
openclaw gateway status         # Is OpenClaw running?
openclaw gateway restart        # Restart (fixes most issues)
openclaw gateway stop           # Stop
openclaw gateway start          # Start
openclaw gateway run            # Run in foreground (with live logs)
openclaw status                 # Show channel health and recent sessions
openclaw health                 # Fetch Gateway health
openclaw --help                 # Show all available commands

Diagnostics \& Troubleshooting

openclaw doctor                 # Health check — detects and reports issues
openclaw doctor --repair        # Like doctor, but tries to fix issues automatically
openclaw logs --follow          # View live logs (Ctrl+C to stop)
openclaw logs --follow --json   # Logs in JSON format (for developers)
openclaw tui                    # Terminal UI — chat directly in the terminal

Exec Approvals (Tool Permissions)

openclaw approvals get                               # Show current permissions
openclaw approvals allowlist add "/bin/bash"         # Allow bash
openclaw approvals allowlist add "/usr/bin/python3"  # Allow Python

Note: If your assistant cannot run terminal commands, it's usually because Exec Approvals are not configured yet. Start with openclaw approvals get and openclaw doctor.

Channels (WhatsApp, Telegram, Discord)

openclaw channels status        # Connection status of all channels
openclaw channels logs          # View channel logs
openclaw configure              # Set up or reconnect channels

Sessions \& Agents

openclaw sessions list          # Show stored sessions
openclaw agents list            # Show all configured agents

Skills \& Updates

openclaw skills list            # Show installed skills
openclaw skills search <name>   # Search for a new skill
openclaw update                 # Update OpenClaw

Security \& Backup

openclaw security audit         # Run a security audit
openclaw backup create          # Create a backup
openclaw backup verify          # Verify a backup

Advanced

openclaw memory search <query>  # Search memory files
openclaw models list            # Show available AI models
openclaw message send --target +43... --message "Test"  # Send a message
openclaw docs                   # Search documentation

Congratulations!

You now have an AI assistant running on Linux!

In your browser: http://127.0.0.1:18789/
Optional WhatsApp/Telegram
Auto-updates

Too complicated? We do it for you.

Managed Hosting — we set up OpenClaw for you and take care of everything.

View all hosting plans Ask a question