DEV Community

Caelum
Caelum

Posted on

Deploy OpenClaw on a VPS with Telegram: A Step-by-Step Guide

#openclaw #ai #telegram #selfhosted

Cloud AI assistants are convenient, but they come with trade-offs: your conversations live on someone else's servers, the assistant forgets you between sessions, and it stops existing the moment you close the tab. OpenClaw takes the opposite approach. It's an open-source AI assistant that runs on your own hardware, keeps its state and memory locally, and talks to you through chat apps you already use — including Telegram.

Running it on your laptop works, but laptops sleep. A $5–10/month VPS keeps your assistant online around the clock. By the end of this guide you'll have:

  • OpenClaw installed on a fresh Ubuntu VPS, running as a background service
  • A private Telegram bot connected to it
  • Pairing-based access control, so only you can talk to it
  • A Control UI you can reach securely — without exposing it to the internet

Let's build it.

Prerequisites

  • A VPS running Ubuntu 22.04 or 24.04 (1–2 GB RAM is enough to start; the heavy lifting happens at the model provider, not on your server). Hetzner, DigitalOcean, Vultr, Linode — any of them works.
  • Root SSH access to the server.
  • A Telegram account.
  • An API key from a model provider (Anthropic, OpenAI, etc.). OpenClaw is bring-your-own-key: you pay the provider directly for usage.
  • About 30 minutes.

Step 1: Prepare the server

SSH in as root, apply updates, and create a dedicated user. OpenClaw can execute commands and work with files, so it should not run as root — give it its own account:

ssh root@your-server-ip

apt update && apt upgrade -y
adduser openclaw
usermod -aG sudo openclaw
Enter fullscreen mode Exit fullscreen mode

Then enable the firewall, allowing only SSH. This matters later: OpenClaw's gateway port (18789) should never be open to the public internet — we simply won't add a rule for it.

ufw allow OpenSSH
ufw enable
Enter fullscreen mode Exit fullscreen mode

Log out and back in as the new user:

ssh openclaw@your-server-ip
Enter fullscreen mode Exit fullscreen mode

Step 2: Install OpenClaw

The official installer detects your OS, provisions a supported Node.js runtime if needed, and installs the CLI:

curl -fsSL https://openclaw.ai/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

(If you'd rather read the script before piping it to bash — a reasonable instinct on a server — download it from https://openclaw.ai/install.sh, inspect it, then run it with bash install.sh.)

Already managing Node.js yourself? Install the published package instead. Note the version requirement: the npm route needs Node 24.16+ or 26.1+, with Node 26 recommended:

npm install -g openclaw@latest --allow-scripts=openclaw
Enter fullscreen mode Exit fullscreen mode

The --allow-scripts=openclaw flag applies to npm 12 (or npm 11.16+). On npm 11.15 and earlier, omit it.

Verify the install:

openclaw doctor
Enter fullscreen mode Exit fullscreen mode

openclaw doctor checks your environment and flags missing pieces before they turn into confusing errors later.

Step 3: Run onboarding and install the daemon

The onboarding wizard walks you through choosing a model provider and entering your API key, then sets up the local state directory (~/.openclaw):

openclaw onboard --install-daemon
Enter fullscreen mode Exit fullscreen mode

The --install-daemon flag registers OpenClaw as a background service (systemd on Linux), so the gateway starts on boot and restarts if it crashes. Follow the wizard prompts; when it asks about chat channels, you can skip for now — we'll add Telegram explicitly in Step 5 so you see exactly what gets configured.

Confirm the gateway is healthy:

openclaw status
openclaw health
Enter fullscreen mode Exit fullscreen mode

Step 4: Create your Telegram bot

OpenClaw doesn't use a shared public bot — you create your own, which means your bot's username and token are yours alone.

  1. In Telegram, open a chat with @botfather (the official bot-management account — double-check the handle).
  2. Send /newbot.
  3. Pick a display name, then a username ending in bot (e.g. my_openclaw_assistant_bot).
  4. BotFather replies with a token that looks like 123456789:ABCdef.... Treat it like a password: anyone holding it controls your bot.

Step 5: Connect Telegram to OpenClaw

The quickest path is the CLI:

openclaw channels add --channel telegram --token <bot-token>
Enter fullscreen mode Exit fullscreen mode

This writes the Telegram channel into your config at ~/.openclaw/openclaw.json. The equivalent config block — useful if you prefer editing files — looks like this:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "<bot-token>",
      "dmPolicy": "pairing",
      "groups": { "*": { "requireMention": true } }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Two settings deserve attention:

  • dmPolicy: "pairing" is the default, and you should keep it. It means the bot ignores strangers: a new sender gets a pairing code, and nothing they send is processed until you approve it from the server.
  • requireMention: true for groups means that if you later add the bot to a group chat, it only responds when mentioned, instead of reacting to every message.

Prefer keeping the token out of the config file? Set it as an environment variable instead — TELEGRAM_BOT_TOKEN — and omit botToken from the config. (If both exist, the config value wins.)

Restart the gateway to pick up the channel, then check that Telegram connected:

openclaw gateway restart
openclaw channels status --probe
Enter fullscreen mode Exit fullscreen mode

You should see Telegram listed as connected, with your bot's username.

Step 6: Pair your account and say hello

Now open Telegram, find your bot, and send it any message — "hi" is fine. Because of the pairing policy, it won't answer yet. Back on the server:

openclaw pairing list telegram
Enter fullscreen mode Exit fullscreen mode

You'll see your pending request with a code. Approve it (codes expire after one hour; if yours lapses, just message the bot again to generate a fresh one):

openclaw pairing approve telegram <PAIRING-CODE>
Enter fullscreen mode Exit fullscreen mode

Send the bot another message. This time it answers — and from now on, that answer comes from your server, running your assistant, reachable from any device where you're logged into Telegram.

Step 7: Reach the Control UI safely

OpenClaw ships with a web Control UI served by the gateway on port 18789 — bound to localhost. Don't change that binding and don't open the port in your firewall. Instead, tunnel it through SSH from your own machine:

ssh -L 18789:127.0.0.1:18789 openclaw@your-server-ip
Enter fullscreen mode Exit fullscreen mode

Then open http://127.0.0.1:18789 in your local browser. The UI is reachable only while the tunnel is up, and only by you.

Common errors

  • The bot never replies. Almost always pairing: you messaged it but never approved the request. Run openclaw pairing list telegram and approve your code.
  • "Invalid token" on startup. The BotFather token was copied incompletely or with stray whitespace. Re-copy the full token, or have BotFather revoke and reissue it.
  • "Telegram channel disabled." The config is missing "enabled": true, or the gateway wasn't restarted after your edit. Config changes only take effect after openclaw gateway restart.
  • npm install fails on sharp / libvips. A global libvips is conflicting. Retry with SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest, or just use the installer script, which handles the runtime for you.
  • Node version errors on the npm route. The package requires Node 24.16+ or 26.1+. Check with node --version; again, the installer script sidesteps this by provisioning a supported runtime.
  • Install runs out of memory on a tiny VPS. On 1 GB instances, add swap before installing: sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile.
  • Pairing code expired. Codes live for one hour. Message the bot again and approve the new code promptly.

What it costs

  • VPS: roughly $5–10/month for a small instance at most providers. OpenClaw itself is free and open source (MIT).
  • Model usage: pay-as-you-go to your API provider. Light personal use typically lands in the $2–10/month range, but it depends entirely on which model you pick and how chatty you are. Set a spending limit in your provider's console if you want a hard ceiling.

Security notes

  • Keep secrets secret. Bot tokens and API keys belong in environment variables or the protected config under ~/.openclaw — never in git repos, screenshots, or shared shell histories. If a token leaks, revoke it (BotFather can reissue bot tokens; your model provider can rotate API keys).
  • Run as a dedicated non-root user, as in Step 1, and keep the OS patched.
  • Port 18789 stays closed. Reach the Control UI through an SSH tunnel or a trusted private network, never the public internet.
  • Keep dmPolicy on pairing or allowlist. Setting it to open lets anyone who finds your bot's username send it commands — a bad idea for an assistant that can run tools.
  • Change defaults. If your VPS provider gave you a default root password, replace it, use SSH keys, and disable password authentication once your key works.

You're done

You now have a personal AI assistant that lives on your server, remembers context between conversations, and answers you in Telegram from anywhere — no subscription, no third-party platform holding your data. From here, the natural next steps are adding skills, connecting a second channel (WhatsApp, Discord, and Slack are all supported), and tuning the assistant's workspace files to your projects.

If you'd rather skip the setup, I offer this as a done-for-you service on Fiverr: http://www.fiverr.com/s/NeeqRgp

Top comments (0)