How to Install OpenClaw on Ubuntu 24.04 with Telegram

Serdar Tekin
Serdar Tekin
Co-Founder & CTO
IntermediateUpdated Nov 17, 202623 min read~45+ minutes total
OpenClawAI AgentUbuntu 24.04TelegramSelf-Hosted AISecurityNode.js
Last reviewed:
Tutorial
How to Install OpenClaw on Ubuntu 24.04 with Telegram
rafftechnologies.com/learn
On this page

Prerequisites

  • An Ubuntu 24.04 VM with SSH sudo access, a non-root administrator, a supported model-provider login or API key, a Telegram account, and a Telegram bot token from @BotFather

Run your own OpenClaw AI agent on a server you control.

Tested on 2 vCPU and 4 GB RAM: $17.99 a month

  1. 1Pick a Linux imageUbuntu, Debian and more, with your SSH key added.
  2. 2Choose a sizeFrom $4.99 a month. Resize when your app grows.
  3. 3Connect over SSHYour server is up in about 55 seconds.

Ubuntu, Debian and other Linux distributions with full root and SSH access, up and running in about 55 seconds.

OpenClaw is a self-hosted AI assistant that connects model providers, tools, messaging channels, and a local control Gateway. On an Ubuntu 24.04 VM, the safest baseline is to keep the Gateway on its default loopback-only bind, run it as the managed user service installed by OpenClaw, connect Telegram through long polling, and avoid opening the Gateway port to the public internet. Telegram does not need an inbound web port in this default mode.

The original tutorial used a Raff Linux VM running Ubuntu 24.04. The saved tested environment remains Ubuntu 24.04 LTS on Raff 2 vCPU / 4 GB RAM VM. This October 27, 2026 update pins OpenClaw 2026.10.7, published October 24, after reviewing the current official release notes. The original VM test environment is preserved as historical metadata; no new complete Raff VM retest of the October build is claimed.

OpenClaw's Gateway listens on port 18789 and binds to loopback by default. Current upstream security guidance explicitly recommends keeping it on loopback where possible, using an SSH tunnel or Tailscale Serve for remote UI access, and never exposing an unauthenticated Gateway on 0.0.0.0. This tutorial therefore does not add a public UFW rule for 18789.

Prerequisites:

  • An Ubuntu 24.04 VM with SSH and sudo access
  • A non-root administrative user
  • A supported model-provider login or API key
  • A Telegram account
  • A Telegram bot token created with the real @BotFather
  • A second SSH session or recovery path before changing firewall/access settings

Step 1 — Verify Ubuntu, resources, SSH, and network exposure

Confirm the OS:

Bash
cat /etc/os-release uname -r

Check memory and disk space:

Bash
free -h df -h /

Confirm your current identity and sudo access:

Bash
id sudo -v

List listening ports before installing anything:

Bash
sudo ss -tulpn

Keep the current SSH session open while you work. Open a second SSH session now so you know the recovery path works before hardening or firewall changes.

Verify: Ubuntu should report 24.04, sudo should work for the administrative user, and you should know which services/ports are already listening before OpenClaw is installed.

Step 2 — Apply Ubuntu updates and check for a required reboot

Update package metadata and review available upgrades:

Bash
sudo apt update apt list --upgradable 2>/dev/null

Apply the updates according to your maintenance policy:

Bash
sudo apt upgrade

Check whether a reboot is required:

Bash
if [ -f /var/run/reboot-required ]; then cat /var/run/reboot-required else echo "No reboot required" fi

If a reboot is required, schedule it before installing the long-running Gateway service, then reconnect and confirm the VM is healthy.

Verify: apt update should finish without repository errors, required security updates should be understood/applied, and any necessary reboot should be completed before continuing.

Step 3 — Inspect and dry-run the official OpenClaw installer

OpenClaw's current recommended Linux installer checks the operating system, verifies or installs a supported Node.js runtime, installs OpenClaw through npm by default, and can manage onboarding. On Linux the installer provisions a supported Node 24 LTS runtime when Node is missing. OpenClaw 2026.10.7 requires Node 24.22.1 or later within Node 24, or 26.12.1 or later within Node 26. Node 26 is the preferred runtime; Node 22, 23, and 25 are not supported. Confirm the selected Node build before completing the installation.

Download the official installer instead of immediately piping it into a shell:

Bash
curl -fsSL --proto '=https' --tlsv1.2 \ https://openclaw.ai/install.sh \ -o /tmp/openclaw-install.sh

Inspect the beginning of the script and its help output:

Bash
head -n 40 /tmp/openclaw-install.sh bash /tmp/openclaw-install.sh --help

Preview the exact install without changing the server:

Bash
bash /tmp/openclaw-install.sh \ --dry-run \ --version 2026.10.7 \ --no-onboard

Verify: The script should come from https://openclaw.ai/install.sh, help output should display normal installer options, and the dry run should target OpenClaw 2026.10.7 without reporting an unsupported platform/runtime.

Step 4 — Install OpenClaw 2026.10.7 and verify the CLI

Run the inspected installer with an exact version pin and skip onboarding for now:

Bash
bash /tmp/openclaw-install.sh \ --version 2026.10.7 \ --no-onboard \ --verify

Start a new shell if the installer updates your PATH, then check:

Bash
openclaw --version node --version

The installer is preferred over sudo npm install -g openclaw@latest because it handles supported Node/runtime checks and avoids common root-owned npm-prefix problems on Linux.

Remove the temporary installer copy when finished:

Bash
rm -f /tmp/openclaw-install.sh

Verify: openclaw --version should report 2026.10.7; node --version must meet the documented Node 24.22.1+ or Node 26.12.1+ requirement. Recheck the linked upstream compatibility guide if installer requirements change.

Step 5 — Run onboarding and install the managed Gateway service

Start OpenClaw's guided setup:

Bash
openclaw onboard --install-daemon

During onboarding:

  • choose the model provider you actually use;
  • authenticate with the provider or enter its API key when prompted;
  • keep the Gateway on its normal local/loopback configuration;
  • install the managed daemon/service;
  • skip optional channels/skills/plugins you do not need yet;
  • keep workspace/state under your user account.

Do not paste provider secrets into screenshots, tickets, shell commands, Git repositories, or public documentation. Use the OpenClaw prompt/configuration flow so credentials are stored in the application's supported state/auth stores.

After onboarding:

Bash
openclaw config validate openclaw doctor

Verify: Configuration validation should pass, openclaw doctor should not report an unresolved critical setup failure, and the managed Gateway service should be installed.

Step 6 — Verify the Gateway service, loopback bind, and default port

Check Gateway state:

Bash
openclaw gateway status

Inspect the configured bind and port:

Bash
openclaw config get gateway.bind openclaw config get gateway.port

If the values are not explicitly authored, OpenClaw's current defaults are loopback and port 18789.

Check the live listener:

Bash
sudo ss -lntp | grep ':18789' || true

The intended security posture is a loopback listener such as:

Text
127.0.0.1:18789

not a public 0.0.0.0:18789 listener.

Check the managed user unit:

Bash
systemctl --user status openclaw-gateway.service --no-pager

OpenClaw's Linux service flow uses a systemd user unit. openclaw doctor also checks systemd lingering so the Gateway can remain alive after logout.

Verify: The Gateway should be running, port 18789 should be loopback-only, and the managed user service should be active without a restart loop.

Step 7 — Apply a messaging-only tool baseline and run the security audit

For a Telegram-first assistant that does not need arbitrary host command execution, start from a narrow tool posture:

Bash
openclaw config set tools.profile messaging openclaw config set tools.exec.security deny openclaw config set tools.exec.ask always openclaw config set tools.elevated.enabled false

Validate the resulting configuration:

Bash
openclaw config validate

Restart if OpenClaw tells you the changed settings require it:

Bash
openclaw gateway restart

Run the security checks:

Bash
openclaw security audit openclaw security audit --deep

Upstream recommends these audits after configuration changes and before expanding network/channel exposure. The deep audit adds live Gateway probes and additional runtime checks.

This restrictive tool profile is a safe starting point, not a requirement for every OpenClaw workflow. If you later enable shell, browser, file-write, elevated, or automation tools, do so deliberately and re-run the audit.

Verify: openclaw config validate should pass, the security audit should have no unexplained critical findings, and dangerous execution/elevated capabilities should remain disabled unless explicitly required.

Step 8 — Protect OpenClaw state and secret-bearing files

OpenClaw's current security checks expect private state permissions. Tighten the main state directory and config file:

Bash
chmod 700 ~/.openclaw

If the config exists:

Bash
chmod 600 ~/.openclaw/openclaw.json

Inspect without printing credential contents:

Bash
stat -c '%a %n' ~/.openclaw stat -c '%a %n' ~/.openclaw/openclaw.json 2>/dev/null || true

OpenClaw state can include model auth profiles, channel credentials, pairing allowlists, session metadata/transcripts, and configuration. Do not sync ~/.openclaw through a broad shared Dropbox/Drive/iCloud folder or copy it into public Git repositories.

Run the built-in secret scan:

Bash
openclaw secrets audit --check

Verify: ~/.openclaw should be owner-only, the config should not be group/world-readable, and the secrets audit should not show an unexplained plaintext or unresolved-secret problem.

Step 9 — Create a Telegram bot and store its token without printing it

In Telegram, verify that the account is exactly:

Text
@BotFather

Create a bot with:

Text
/newbot

Save the token privately. OpenClaw's Telegram integration supports a config token, token file, or TELEGRAM_BOT_TOKEN environment fallback for the default account. This tutorial uses the environment fallback so the bot token is not copied into openclaw.json.

Create/update OpenClaw's private environment file:

Bash
mkdir -p ~/.openclaw touch ~/.openclaw/.env chmod 600 ~/.openclaw/.env sed -i '/^TELEGRAM_BOT_TOKEN=/d' ~/.openclaw/.env read -s -p "Telegram bot token: " TELEGRAM_BOT_TOKEN echo printf 'TELEGRAM_BOT_TOKEN=%s\n' "$TELEGRAM_BOT_TOKEN" >> ~/.openclaw/.env unset TELEGRAM_BOT_TOKEN

Register the Telegram channel using the environment value:

Bash
openclaw channels add --channel telegram --use-env

Validate and restart if requested:

Bash
openclaw config validate openclaw gateway restart

Verify: Telegram should appear as a configured channel, the token should not be visible in openclaw config get output, and ~/.openclaw/.env should have mode 600.

Step 10 — Pair your Telegram DM with the Gateway

Open the actual bot you created and send it a direct message such as:

Text
/start

OpenClaw's default Telegram DM policy is pairing. Unknown senders receive a one-time pairing code; current upstream documentation says the code expires after one hour.

On the VM, list pending Telegram pairings:

Bash
openclaw pairing list telegram

Approve only the code associated with your own Telegram account:

Bash
openclaw pairing approve telegram PAIRING_CODE

Do not change the DM policy to a globally open mode just to avoid pairing. If multiple people will message the bot, use explicit allowlists/pairing and treat each approved sender as delegated authority over whatever tools the agent is allowed to use.

Verify: Your Telegram account should be approved, an unknown unapproved sender should not gain normal bot access, and openclaw doctor should not report an intentionally open DM policy.

Step 11 — Send an end-to-end Telegram test message

Run a final health check before messaging:

Bash
openclaw gateway status openclaw doctor openclaw security audit

Then send the bot:

Text
Reply with exactly: OpenClaw is running on Ubuntu 24.04.

The response proves the complete path:

Text
Telegram -> OpenClaw channel -> Gateway -> model provider -> Gateway -> Telegram

OpenClaw AI agent responding through Telegram on Ubuntu 24.04

The old screenshot may show an earlier OpenClaw UI/message format; use the successful Telegram round trip, current CLI status, and current logs as the authority for this revision.

Verify: The approved Telegram account should receive a valid model response, the Gateway should remain healthy, and no public port should have been required for Telegram long polling.

Step 12 — Access the Control UI remotely through an SSH tunnel

Do not expose the Control UI directly to the public internet.

From your local workstation, open an SSH tunnel to the VM:

Bash
ssh -N -L 18789:127.0.0.1:18789 your_user@your_server_ip

Keep that terminal running.

On the VM, generate a short-lived browser handoff without trying to launch a GUI browser on the server:

Bash
openclaw dashboard --no-open

If you need the current structured browser handoff data:

Bash
openclaw dashboard --json

Then use the tunnel from your local browser. The base local endpoint is:

Text
http://127.0.0.1:18789/

Current OpenClaw dashboard guidance recommends localhost, Tailscale Serve, or an SSH tunnel. The openclaw dashboard command issues a short-lived one-time browser pairing/bootstrap rather than printing the shared Gateway secret in normal interactive output.

Verify: The Control UI should load through the SSH tunnel while sudo ss -lntp | grep 18789 still shows the Gateway only on loopback.

Step 13 — Back up OpenClaw state before upgrades or major configuration changes

Current OpenClaw includes a first-party backup command. Create a protected backup directory outside the live ~/.openclaw tree:

Bash
mkdir -p ~/Backups/openclaw chmod 700 ~/Backups/openclaw

Create and immediately verify a full archive:

Bash
openclaw backup create \ --output ~/Backups/openclaw \ --verify

List the resulting archives:

Bash
ls -lh ~/Backups/openclaw

You can separately verify an archive later:

Bash
openclaw backup verify ~/Backups/openclaw/YOUR_BACKUP_FILE.tar.gz

The full backup can contain state, configuration, model/channel credentials, sessions, and workspaces. Treat it like a credential-bearing secret archive: restrict permissions, encrypt/protect remote copies, and do not upload it to a public repository.

Raff Data Protection can add infrastructure-level recovery; the OpenClaw application backup remains valuable before application updates and migrations.

Verify: openclaw backup create --verify should complete successfully and produce a protected archive outside the active OpenClaw state directory.

Step 14 — Update, troubleshoot, audit, and remove OpenClaw safely

Preview future updates first:

Bash
openclaw update --dry-run openclaw update status --json

Before a significant update, create a verified backup. Then update through OpenClaw's supported updater:

Bash
openclaw update

The updater detects the installation type, updates the package/channel, runs health checks, and restarts the managed Gateway when appropriate.

After every update:

Bash
openclaw --version openclaw config validate openclaw gateway status openclaw doctor openclaw security audit --deep

If Telegram stops responding:

Bash
openclaw pairing list telegram openclaw logs --follow

If the Gateway is unreachable locally:

Bash
openclaw gateway status --deep sudo ss -lntp | grep ':18789' || true

If configuration changes fail:

Bash
openclaw config validate openclaw doctor --json

If you suspect secret leakage:

Bash
openclaw secrets audit --check

Rotate any exposed provider key or Telegram token at its source; deleting shell history does not revoke a credential that has already been copied elsewhere.

For removal, create a final backup first, then preview the uninstall:

Bash
openclaw backup create --output ~/Backups/openclaw --verify openclaw uninstall --dry-run

To remove service, state, and workspace interactively:

Bash
openclaw uninstall --all

The OpenClaw CLI itself is removed separately according to its installation method; for an npm-based install, use the supported uninstall guidance rather than deleting random files from ~/.openclaw while the Gateway is still running.

Final audit:

Bash
openclaw gateway status openclaw security audit --deep sudo ss -lntp | grep -E ':(22|18789)\b' || true

Expected architecture:

Text
Telegram | | outbound long polling / Bot API v OpenClaw Gateway 127.0.0.1:18789 | +--> model provider +--> approved messaging tools Admin browser | | SSH tunnel v 127.0.0.1:18789

Verify: The Telegram bot should answer only approved users according to policy, the Gateway should remain loopback-only, the security audit should have no unexplained critical findings, and a verified backup should exist before any major update or removal.

Conclusion

You now have OpenClaw installed on Ubuntu 24.04 with its official installer, a managed Gateway service, a supported Node runtime, Telegram pairing, a messaging-first tool posture, private state permissions, remote Control UI access through an SSH tunnel, and a first-party verified backup workflow.

The key security boundary is the Gateway. Telegram long polling does not require you to publish port 18789, and the Control UI should stay on localhost unless you deliberately adopt a secure remote-access design such as Tailscale Serve or a tightly controlled authenticated proxy. Every new skill, plugin, channel, browser capability, shell tool, or approved sender expands what the agent can do, so re-run openclaw security audit --deep whenever that authority changes.

For adjacent procedures, continue with Harden Ubuntu 24.04, Set Up UFW Firewall, or Build a Remote Development VM.

Deploy a Raff Ubuntu Linux VM for an OpenClaw assistant with a loopback-only Gateway, protected credentials, Telegram pairing, and a tested recovery path. Keep its Node runtime and OpenClaw release patched.

Tested on 2 vCPU and 4 GB RAM: $17.99 a month · 14-day money-back guarantee

Deploy Your Server
Was this article helpful?
Serdar Tekin
Serdar Tekin
Co-Founder & CTO

Co-Founder & CTO at Raff, focused on cloud infrastructure, systems architecture, security, reliability, and production operations.

Run your own OpenClaw AI agent on a server you control.

Tested on 2 vCPU and 4 GB RAM: $17.99 a month

Ubuntu, Debian and other Linux distributions with full root and SSH access, up and running in about 55 seconds.

14-day money-back guarantee

Frequently asked questions

How do I install OpenClaw on Ubuntu 24.04?
Use the official OpenClaw Linux installer after reviewing its instructions. This guide pins OpenClaw 2026.10.7 (released October 24, 2026) and runs guided onboarding to install the managed Gateway service. It preserves the earlier VM test record and does not claim a new test of this release.
Does OpenClaw require Node.js on Ubuntu?
Yes. OpenClaw 2026.10.7 requires Node 24.22.1+ within the Node 24 line or Node 26.12.1+ within Node 26. Node 26 is recommended; Node 22, 23 and 25 are unsupported. The official installer checks the Node runtime and may install a compatible version.
Do I need to open port 18789 for Telegram?
No. Telegram uses long polling by default, so a normal Telegram bot integration does not require an inbound Gateway port. Keep the Gateway on its default loopback bind and do not add a public UFW rule for 18789.
How should I access the OpenClaw dashboard on a VPS?
Prefer an SSH tunnel or Tailscale Serve rather than exposing the Control UI publicly. With SSH, forward local port 18789 to `127.0.0.1:18789` on the VM and use `openclaw dashboard` for the authenticated browser handoff.
How does Telegram pairing work in OpenClaw?
Telegram DMs use pairing by default. An unknown sender receives a one-time code; review it on the Gateway host with `openclaw pairing list telegram` and approve only the intended account. Pairing codes currently expire after one hour.
Where does OpenClaw store sensitive data?
OpenClaw state under `~/.openclaw` can include config, model authentication, channel credentials, pairing records, sessions, and workspace data. Keep the directory owner-only, avoid public/synced storage, and use the built-in security and secrets audits.
How do I back up OpenClaw?
Use the first-party `openclaw backup create --output <directory> --verify` command. A full archive can contain credentials and sessions, so protect it like the live state directory and keep a secure copy away from the VM.
How do I safely update OpenClaw?
Create a verified backup, preview with `openclaw update --dry-run`, then use `openclaw update`. Afterward run config validation, Gateway status, doctor, and `openclaw security audit --deep` before relying on the updated agent.