# ClawReady.in - Full Knowledge Dump > ClawReady.in is an independent educational resource and setup service. It is not affiliated with, endorsed by, or operated by OpenClaw. This document contains the full text of all guides, troubleshooting steps, recipes, and glossary terms from ClawReady.in. ## Collection: GUIDES ### Why You Need a Dedicated WhatsApp Number for OpenClaw URL: https://www.clawready.in/guides/dedicated-whatsapp-number-openclaw/ Description: Connecting your personal WhatsApp to an AI agent is a privacy disaster. Learn why you need a dedicated number, and the best options in India. When setting up the OpenClaw WhatsApp integration (usually via the Baileys library or similar web.whatsapp.com wrappers), the agent logs into an actual WhatsApp account via a QR code. > [!NOTE] If you scan the QR code with your primary, personal WhatsApp account, the OpenClaw agent will have read access to **every message, photo, and voice note you receive from friends and family.** It may also reply to them automatically if not configured properly. Using a dedicated number creates a permanent "sandbox" for your AI workflow. It guarantees that personal chats never cross paths with your AI prompt context. ## Options for Indian Builders If you are based in India, you have two primary paths for acquiring a dedicated number: Physical SIM cards or Virtual Numbers. ### 1. Physical Prepaid SIM (Recommended) Getting a secondary physical SIM is the cheapest, most reliable, and most secure method in India. - **Providers:** Jio, Airtel, Vi. - **Cost:** ~₹250 - ₹300 for the initial SIM + first month recharge. Maintenance is around ₹155/month (Airtel/Vi minimal validity packs) or ~₹1500/year. - **Pros:** 100% reliable SMS OTP delivery. Low risk of being banned by WhatsApp immediately. You legally own the number via Aadhaar KYC. - **Cons:** Requires a dual-SIM phone or a spare older phone to receive the initial OTP. > [!NOTE] If you only need the SIM to receive the initial WhatsApp OTP and keep the account alive, Jio's ₹155/month or Airtel's ₹155/month plans are ideal. You do not need a data plan for the secondary SIM since the OpenClaw VPS will be handling all the actual internet traffic. ### 2. Virtual Numbers (e.g., Twilio, Exotel, Doosra) Virtual numbers are cloud-based phone numbers that can receive SMS. - **Cost:** Varies wildly. Twilio charges monthly fees + per SMS costs. - **Pros:** No physical SIM required. Can be automated. - **Cons:** **High risk of WhatsApp bans.** WhatsApp actively blocks registrations from known virtual VoIP number blocks (like Twilio or TextNow) to prevent spam. > [!NOTE] Do not use free SMS verification sites. These numbers are public. If you register WhatsApp with a public number, anyone else using that site can request a new OTP and hijack your WhatsApp account, stealing access to your OpenClaw bot. ### 3. WhatsApp Business API If you are building a commercial application with high message volume, the unofficial Baileys web-wrapper is not suitable. You must apply for the official WhatsApp Business API (via Meta or providers like Interakt/Wati). - **Cost:** Per-conversation pricing. - **Pros:** Zero risk of getting banned. Official support. - **Cons:** High setup cost. Strict message template rules. Harder to integrate with standard OpenClaw agents without custom API handlers. ## Setting Up Your Dedicated Number Once you have your new SIM: 1. Insert it into a spare phone (or dual-SIM slot). 2. Download **WhatsApp Business** (this keeps it separate from your personal regular WhatsApp app). 3. Register with the new number. 4. Set the profile name to your AI Agent's name (e.g., "Company Triage Bot"). 5. When running the OpenClaw WhatsApp setup, scan the terminal QR code using this new WhatsApp Business app. You can now safely give this phone number to clients or team members to interact with the AI, with zero risk to your personal privacy. --- ### Fresh Ubuntu VPS Setup for OpenClaw URL: https://www.clawready.in/guides/fresh-ubuntu-vps-setup/ Description: Prepare a fresh Ubuntu VPS with a non-root user, secure SSH keys, and UFW firewall before installing OpenClaw. ## Who this is for This guide is for anyone setting up a brand-new Ubuntu VPS who needs to secure it before installing OpenClaw. It assumes you have a clean server with root access. ## Prerequisites - A fresh Ubuntu VPS (e.g., Ubuntu 22.04 or 24.04). - The public IP address of your VPS. - The `root` password or SSH key provided by your hosting provider. ## Why this matters A brand-new VPS is completely exposed to the internet. If you install OpenClaw as the `root` user, any vulnerability in a dependency or model could compromise your entire server. Setting up a non-root user and a firewall is the most important step you can take. > [!NOTE] Using UFW (Uncomplicated Firewall) protects your VPS from automated port scanners and brute-force attacks. However, ensure you explicitly allow OpenSSH before enabling UFW, or you will be permanently locked out of your server. ## VPS Preparation Steps
  1. ### Log in as root Open your terminal and connect to the VPS using the root account.
  2. ### Create a new user Create a new user specifically for running OpenClaw. We'll call it `clawuser`. Follow the prompts to set a strong password. You can leave the name and phone fields blank.
  3. ### Grant sudo privileges Add the new user to the `sudo` group so it can run administrative commands.
  4. ### Set up the UFW Firewall Only allow SSH (port 22), HTTP (port 80), and HTTPS (port 443). **Do not allow port 18789.**
  5. ### Test the new user Open a *new* terminal window (do not close the root one yet) and try logging in as `clawuser`. If it works, you can safely log out of root.
## Bad Output / Common Mistakes - **UFW locked you out:** If you ran `ufw enable` before `ufw allow OpenSSH`, you might get locked out. You will need to use your VPS provider's web console to log in and fix it. - **Permission Denied:** If `sudo apt update` fails as `clawuser`, you forgot to run the `usermod` command. ## Rollback / Undo If you made a mistake and want to start over, you can revert the changes as root: - **Delete the user:** - **Reset UFW:** ## Next steps Now that your server is secure and you have a non-root user, you are ready to proceed with the [OpenClaw Installation Guide](/guides/install-openclaw-ubuntu-vps). If you need hands-on assistance configuring your server or run into complex firewall issues, check out our [Setup Help](/setup-help) page. ## Sources - OpenClaw Docs - Getting Started: [https://docs.openclaw.ai/start/getting-started](https://docs.openclaw.ai/start/getting-started) (Checked on 2026-06-03) - Ubuntu UFW Documentation: [https://manpages.ubuntu.com/manpages/noble/man8/ufw.8.html](https://manpages.ubuntu.com/manpages/noble/man8/ufw.8.html) (Checked on 2026-06-03) --- ### Install OpenClaw on Ubuntu VPS URL: https://www.clawready.in/guides/install-openclaw-ubuntu-vps/ Description: The complete, step-by-step field manual for installing OpenClaw Gateway on an Ubuntu VPS. Covers Node.js setup, workspace creation, and verifying your installation safely. ## Short answer Installing OpenClaw on an Ubuntu VPS requires three main phases: 1. Installing Node.js (via `nvm`) 2. Initializing an OpenClaw workspace directory 3. Starting the Gateway process and accessing it safely via an SSH tunnel This guide walks you through the entire process, assuming you are starting with a fresh Ubuntu server. ## Who this is for This guide is for Indian builders, freelancers, and small businesses who want to run OpenClaw 24/7 on a remote server (a [VPS](/glossary/vps)). You should use this guide if you are deploying to providers like DigitalOcean, Hetzner, AWS Lightsail, or Hostinger. ## Prerequisites Before running any commands in this guide, you **must** have: - An Ubuntu VPS (22.04 or 24.04 LTS recommended) - SSH access configured - A non-root user with `sudo` privileges (e.g., `clawuser`) If you have not done this yet, stop and complete the [Fresh Ubuntu VPS Setup](/guides/fresh-ubuntu-vps-setup) guide first. Never install or run OpenClaw using the `root` user. Doing so gives the application (and any tools you enable) complete control over your server. Always log in as your non-root user (e.g., `clawuser`). ## Step 1: Install Node.js using nvm OpenClaw is a Node.js application. We recommend installing Node.js using `nvm` (Node Version Manager) rather than `apt`, because it avoids permission issues and lets you easily switch versions. First, install `nvm`: To make `nvm` available immediately, reload your shell configuration: Now, install the latest LTS (Long Term Support) version of Node.js: Verify the installation: ## Step 2: Create a workspace OpenClaw requires a dedicated folder for its configuration, logs, and local SQLite database. Create a folder and move into it: Initialize a new project: ## Step 3: Install the OpenClaw package Install the OpenClaw core package locally in your workspace: Verify that the CLI is available: ## Step 4: Start the Gateway It is time to start the Gateway for the first time. The Gateway will automatically generate a default configuration file (`.env`) if one does not exist. You should see logs indicating the Gateway has started: By default, the Gateway binds to `127.0.0.1` (localhost). This means it is invisible to the internet. Do not change this to `0.0.0.0` or run `sudo ufw allow 18789` unless you are configuring a secure reverse proxy. Public exposure without authentication is highly dangerous. ## Step 5: Access the Dashboard safely Because the Gateway is running on `127.0.0.1` on your VPS, you cannot just type the VPS IP address into your browser. You must create an **[SSH Tunnel](/glossary/ssh)**. Open a **new** terminal window on your local laptop (do not close the terminal running OpenClaw) and run: Now, open your web browser and go to: `http://localhost:18789` You should see the OpenClaw dashboard! ## Step 6: Stop the Gateway Go back to the terminal where `npx openclaw start` is running and press `Ctrl+C` to stop the Gateway. Why stop it? Because running a server attached to your SSH session means it will die the moment you close your laptop. In a later guide, we will use a process manager (`pm2`) to keep it running 24/7. ## Common install failures **Error: EACCES: permission denied, mkdir** - **Cause:** You probably used `sudo npm install`. - **Fix:** Never use `sudo` with `npm`. Change ownership of the folder back to your user (`sudo chown -R $USER:$USER ~/openclaw-workspace`) and run `npm install` without sudo. **Error: Node version too old** - **Cause:** You installed Node.js via Ubuntu's default `apt` repository, which often provides outdated versions. - **Fix:** Remove the apt version (`sudo apt remove nodejs`) and follow Step 1 to install via `nvm`. **Gateway starts, but dashboard won't load** - **Cause:** The SSH tunnel is not running, or you bound the Gateway to an IP other than localhost. - **Fix:** Verify the tunnel command in Step 5. See [Dashboard Not Opening](/troubleshooting/dashboard-not-opening) for detailed troubleshooting. ## What not to do - **Do not share your `.env` file.** It contains secret keys. - **Do not run `ufw allow 18789`.** It exposes your Gateway to the internet. - **Do not use `npm install -g`.** Install OpenClaw locally in a workspace folder so you have a self-contained environment. ## Uninstall / Rollback If you need to start completely fresh, simply delete the workspace folder and its contents: ## Next steps Now that OpenClaw is installed and you know how to access the dashboard safely, you need to secure your VPS before connecting channels or AI models. Go to: [OpenClaw VPS Security Checklist](/guides/openclaw-vps-security-checklist) ## When to ask for setup help If you are stuck on permission errors, Node.js issues, or the Gateway keeps crashing, use the [Setup Help](/setup-help) service. We can help you audit your setup without asking for any raw secrets or root passwords. **Remember:** Before sharing any logs with the community or support, redact your API keys, tokens, and IP addresses. --- ### Install OpenClaw Without Docker URL: https://www.clawready.in/guides/install-openclaw-without-docker/ Description: A no-Docker OpenClaw install path for users who prefer Node-based setup and direct VPS service management. ## Introduction Installing OpenClaw directly on your VPS without using Docker gives you full control over the process environment, directory structure, and local dependencies. This guide walks you through cloning, compiling, configuring, and starting OpenClaw safely. > [!NOTE] Agar aap Docker seekhna nahi chahte ya system memory kam hai, toh aap directly Node.js ka use karke OpenClaw set up kar sakte hain. Lekin isme config, process restarts, aur updates manually handle karne honge. --- ## Prerequisites Before starting, ensure you have: 1. An updated Ubuntu VPS with basic UFW firewall enabled. 2. Node 24 LTS and npm installed (see the [Node 24 Setup Guide](/guides/node-24-openclaw-setup)). 3. Git installed: ```bash sudo apt-get install -y git ``` --- ## Step 1: Clone OpenClaw Repo Create a dedicated folder for your project and clone the codebase: ```bash mkdir -p ~/openclaw-setup cd ~/openclaw-setup git clone https://github.com/OpenClaw/openclaw.git . ``` --- ## Step 2: Install Dependencies OpenClaw has specific npm dependencies. Install them using: ```bash npm install ``` This will download all node packages under `node_modules`. If you run into build errors (e.g. node-gyp issues), verify you have the standard compiler tools: ```bash sudo apt-get install -y build-essential ``` --- ## Step 3: Configure Gateway & Secrets Do not run OpenClaw before setting up your config. ### Create Configuration File Copy the sample config template: ```bash cp config.example.yaml config.yaml ``` ### Edit Configuration Open `config.yaml` using your favorite CLI editor (e.g. `nano`): ```bash nano config.yaml ``` ### Safety Warning > [!CAUTION] > **Never check this `config.yaml` file into any public GitHub repository.** It will contain your database passwords, Telegram bot tokens, and WhatsApp sessions. Ensure the Gateway listens only on the local interface to prevent public scanning: ```yaml gateway: host: "127.0.0.1" # Do NOT set this to "0.0.0.0" (Public) port: 18789 ``` --- ## Step 4: Verify with Doctor CLI OpenClaw provides a doctor command to inspect your environment and verify database/redis connectivity: ```bash npm run openclaw doctor ``` **Good Output Example:** ```text ✔ Node version matches requirements (v24.x) ✔ Config file found and parsed successfully ✔ Database connection successful ✔ Redis connection status: OK ``` --- ## Step 5: Secure Remote Access (SSH Tunneling) Since we bound the Gateway to `127.0.0.1` (loopback only) for security, you cannot open the dashboard directly using `http://your-vps-ip:18789`. Instead, create a secure SSH tunnel from your local PC. ### SSH Tunnel Command (Run on your local computer's command prompt): ```bash ssh -L 18789:127.0.0.1:18789 user@your-vps-ip ``` Once connected, open your local browser and navigate to: ```text http://localhost:18789 ``` This routes all dashboard traffic securely through SSH, bypassing the public internet firewall entirely. --- ## Next Steps If you close your SSH terminal, the OpenClaw process will terminate. Proceed to [Run OpenClaw After Logout](/guides/run-openclaw-after-logout) to configure PM2 or systemd to daemonize your setup. --- ### Node 24 Setup for OpenClaw URL: https://www.clawready.in/guides/node-24-openclaw-setup/ Description: Prepare a compatible Node runtime for OpenClaw and avoid common PATH, npm, and shell confusion. ## Why Node 24? OpenClaw requires a stable and compatible version of Node.js to run the Gateway, plugins, and CLI tools. **Node 24 (LTS)** is the recommended version. Older Node versions (like Node 16 or 18) lack modern JavaScript features and will crash during dependency installation, while extremely new experimental versions might cause compatibility warnings. > [!NOTE] Simple words mein, Node.js ek javascript runtime environment hai jo OpenClaw ke server code ko run karne ke liye zaroori hai. Agar Node version purana hoga, toh dashboard aur bot tools break ho jayenge. --- ## Method 1: Install using NVM (Recommended) NVM (Node Version Manager) is the best way to install and manage Node.js because it allows you to switch between versions easily without messing up system-level folders. ### Step 1: Install NVM Run the official installer script to download and install NVM: ```bash curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash ``` ### Step 2: Load NVM into your current shell session To start using NVM without restarting your terminal, load it by running: ```bash export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion ``` ### Step 3: Install Node 24 Install the latest Node 24 LTS release: ```bash nvm install 24 nvm use 24 nvm alias default 24 ``` ### Step 4: Verify installation Run these commands to confirm Node and NPM are installed: ```bash node -v npm -v ``` Expected output: - Node: `v24.x.y` (e.g. `v24.1.0`) - NPM: `10.x.y` or newer. --- ## Method 2: Install via NodeSource APT (System-Wide) If you are setting up OpenClaw to run under a dedicated system user (e.g. `openclaw`) or using a systemd service that needs a global path, installing via NodeSource APT is preferred. ### Step 1: Download and import the NodeSource security GPG key Run this command to fetch the NodeSource setup script and add it to your package manager: ```bash sudo apt-get update sudo apt-get install -y curl grid-ui gnupg curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg ``` ### Step 2: Create NodeSource repository list Inject the Node 24 repository URL: ```bash NODE_MAJOR=24 echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list ``` ### Step 3: Install Node.js Update your local index and install: ```bash sudo apt-get update sudo apt-get install nodejs -y ``` ### Step 4: Verify system installation ```bash node -v npm -v ``` Expected output: - `v24.x.y` running from `/usr/bin/node`. --- ## Troubleshooting Common Errors ### 1. `Command 'node' not found` after logging out This happens when you install Node using NVM, but your process manager (like PM2 or systemd) doesn't load the shell profile (`.bashrc` or `.zshrc`) where NVM is initialized. - **Fix:** Either use the absolute path to the Node binary in your service configs (e.g. `/home/ubuntu/.nvm/versions/node/v24.x.y/bin/node`) or install Node globally via Method 2. ### 2. EACCES Permission errors during npm global install If you run `npm install -g pm2` and get permission errors, you are trying to install global packages into a directory owned by root. - **Fix:** If using NVM, this shouldn't happen. If using APT, configure a custom prefix for global packages or run: ```bash sudo npm install -g pm2 --unsafe-perm ``` --- ## Next Steps Now that Node 24 is configured, you can proceed to: - Read [Install OpenClaw without Docker](/guides/install-openclaw-without-docker) - Learn how to keep OpenClaw running in the background with [Run OpenClaw After Logout](/guides/run-openclaw-after-logout) --- ### Understanding OpenClaw Gateway Port 18789 URL: https://www.clawready.in/guides/openclaw-gateway-port-18789/ Description: Why OpenClaw uses port 18789, why you should never expose it publicly without authentication, and how to access your dashboard safely using SSH tunnels or Tailscale. ## Short answer OpenClaw Gateway listens on **port 18789** by default. This port serves the dashboard, the API, and the channel coordination layer. By default, it binds to `127.0.0.1` (localhost only), which means only processes on the same server can reach it. **Never open this port in your firewall.** Use an SSH tunnel or Tailscale to access the dashboard from your laptop. ## Who this is for - You just installed OpenClaw and want to access the web dashboard. - You are getting `ERR_CONNECTION_REFUSED` when trying to open the dashboard. - You found a tutorial that suggests running `ufw allow 18789` — and you want to understand why that is dangerous. - You need persistent dashboard access without exposing your server. ## Prerequisites - A running OpenClaw Gateway instance (see [Install OpenClaw on Ubuntu VPS](/guides/install-openclaw-ubuntu-vps)) - SSH access to your server - Basic familiarity with terminal commands ## What port 18789 exposes The Gateway is not a simple web page. When you expose port 18789, you expose: | What is accessible | Risk | |-------------------|------| | Dashboard UI | Anyone can view your conversations, config, and logs | | Channel tokens | Telegram bot tokens and WhatsApp sessions can be read | | API key references | Model provider keys may be visible in config views | | Tool execution | Connected tools (file access, shell, APIs) can be triggered | | Agent control | Anyone can send messages that the agent will process | This is fundamentally different from exposing a normal website on port 80 or 443. The following commands are the most common way beginners accidentally expose their setup. Do not run them unless you have TLS, authentication, and reverse proxy hardening in place. ```bash # DO NOT run this — exposes Gateway to the entire internet openclaw start --host 0.0.0.0 # DO NOT run this — opens port to public internet scanners sudo ufw allow 18789 ``` ## How to access the dashboard safely ### Method 1: SSH tunnel (recommended for quick checks) An SSH tunnel forwards a port from your VPS to your local machine through an encrypted connection. No firewall changes needed. **On your laptop** (not on the VPS), open a terminal and run: Then open your browser and go to `http://localhost:18789`. The traffic is encrypted and completely private — the port is never exposed to the internet. **Windows users:** If using PowerShell or WSL, the same command works. If using PuTTY, configure an SSH tunnel in Connection → SSH → Tunnels: source port `18789`, destination `localhost:18789`. > [!NOTE] SSH tunneling is best for occasional checks — reviewing logs, testing a config change, or verifying that the dashboard loads. The tunnel closes when you close the terminal. ### Method 2: Tailscale / private VPN (recommended for persistent access) If you need always-on dashboard access without running an SSH tunnel every time, install [Tailscale](https://tailscale.com/) on both your VPS and your laptop. Tailscale creates a secure private network between them. 1. Install Tailscale and authenticate on both machines. 2. Find your VPS's Tailscale IP (e.g., `100.x.y.z`). 3. Start the Gateway bound to the Tailscale IP: 4. Access the dashboard at `http://100.x.y.z:18789` from your laptop. See the full [Tailscale setup guide](/guides/openclaw-tailscale-setup) for detailed instructions. ### Method 3: Reverse proxy with TLS and auth (advanced users only) For production deployments where multiple team members need access, you can use Nginx as a reverse proxy with TLS (HTTPS) and HTTP Basic Auth or OAuth. This is significantly more complex and is **not recommended for beginners**. > [!NOTE] A reverse proxy alone does not make Gateway safe. You need TLS certificates (via Certbot/Let's Encrypt), authentication (HTTP Basic Auth minimum), rate limiting, and careful access logging. Misconfiguring any of these defeats the purpose. ## Check your current exposure Run this command on your VPS to see how the Gateway is bound: **Good output (safe — Gateway is private):** The key is `127.0.0.1:18789` — this means the Gateway only accepts connections from inside the server. **Bad output (exposed — take action immediately):** `0.0.0.0:18789` means the Gateway is listening on all network interfaces, including the public internet. ## If you accidentally exposed port 18789 If your Gateway has been bound to `0.0.0.0`, or if you ran `ufw allow 18789`, assume your session data, API keys, and channel tokens have been visible to the internet. Stop the Gateway, close the port, and rotate all credentials. ### Step 1: Stop the Gateway ### Step 2: Remove the UFW rule ### Step 3: Check your provider's firewall Most VPS providers (Hetzner, DigitalOcean, AWS, Hostinger) have a web-based firewall in addition to UFW. Log into your provider's control panel and verify that no external allow rule for port 18789 exists in their firewall settings. ### Step 4: Rotate credentials If the Gateway was exposed for any period of time, rotate: - All AI model API keys (Anthropic, OpenAI, etc.) - Telegram bot tokens (revoke via BotFather, create new ones) - WhatsApp sessions (re-pair with a new QR code) - Any other tokens or secrets in your `.env` file ### Step 5: Restart safely Restart the Gateway bound to localhost: ## Provider-specific firewall notes | Provider | Where to check | Notes | |----------|---------------|-------| | DigitalOcean | Networking → Firewalls | Droplet firewalls are separate from UFW. Check both. | | Hetzner | Firewalls → your-firewall | Hetzner cloud firewalls override UFW. If port 18789 is allowed in Hetzner's panel, UFW cannot block it from the outside. | | AWS Lightsail | Networking → IPv4 Firewall | Lightsail has its own firewall UI. UFW runs inside the instance. | | Hostinger | VPS → Manage → Firewall | Hostinger's panel firewall is independent of UFW. | ## What not to do - **Do not bind to `0.0.0.0`** unless you have TLS, auth, and reverse proxy hardening in place. - **Do not run `sudo ufw allow 18789`** as a fix for "dashboard not opening." The fix is an SSH tunnel. - **Do not disable UFW** to troubleshoot Gateway access. - **Do not share screenshots** of your dashboard or `ss` output without redacting IPs and PIDs. - **Do not assume your provider's firewall protects you** — always verify with `ss` on the server itself. ## Prevention checklist - [ ] Gateway is bound to `127.0.0.1` (verify with `sudo ss -tulpn | grep 18789`) - [ ] UFW does not have a rule for port 18789 (verify with `sudo ufw status numbered`) - [ ] Provider's web-panel firewall does not allow 18789 - [ ] Dashboard access is via SSH tunnel or Tailscale only - [ ] `.env` file has `chmod 600` permissions - [ ] API keys and tokens are not committed to Git ## When to ask for help If you suspect your Gateway has been exposed, or if you are unsure whether your setup is safe, request a [Config Review](/setup-help). We can check your network exposure, firewall rules, and access patterns using only redacted logs — we will never ask for your raw API keys, bot tokens, or passwords. ## Related guides - [OpenClaw VPS Security Checklist](/guides/openclaw-vps-security-checklist) - [Fix: Dashboard Not Opening](/troubleshooting/dashboard-not-opening) - [Fix: Gateway Not Running](/troubleshooting/gateway-not-running) - [Tailscale Setup for OpenClaw](/guides/openclaw-tailscale-setup) - [Glossary: Port](/glossary/port) - [Glossary: SSH](/glossary/ssh) ## Sources - OpenClaw Docs — Security: [https://docs.openclaw.ai/gateway/security](https://docs.openclaw.ai/gateway/security) (Checked on 2026-06-23) - OpenClaw Docs — Remote Access: [https://docs.openclaw.ai/gateway/remote](https://docs.openclaw.ai/gateway/remote) (Checked on 2026-06-23) - Tailscale Docs: [https://tailscale.com/kb/](https://tailscale.com/kb/) (Checked on 2026-06-23) --- ### Hostinger VPS Setup for OpenClaw URL: https://www.clawready.in/guides/openclaw-hostinger-vps/ Description: A provider-specific walkthrough for deploying OpenClaw on a Hostinger VPS. Includes OS selection, panel navigation, and built-in firewall rules. Hostinger is a popular and cost-effective VPS provider in India. While the general Ubuntu setup guide applies to any VPS, Hostinger's `hPanel` has some specific quirks you should be aware of when deploying OpenClaw. ## 1. Choosing the Right Plan OpenClaw Gateway and an associated Agent process can run on a 1GB RAM machine, but 2GB is recommended for smooth PM2 daemon operation and database overhead. - **KVM 1 (1GB RAM):** Sufficient for a personal bot with a single channel (e.g., Telegram). - **KVM 2 (2GB RAM):** Recommended. Provides enough headroom for running multiple channels (WhatsApp + Telegram) and executing complex tools without out-of-memory (OOM) crashes. ## 2. OS Selection (Ubuntu 22.04 LTS) When setting up your VPS in hPanel: 1. Go to **VPS** -> **Manage** -> **OS & Panel**. 2. Select **Operating System**. 3. Choose **Ubuntu** and select version **22.04 64bit**. 4. Set a strong `root` password. You will need this for the initial SSH connection. > [!NOTE] While Ubuntu 24.04 is out, stick to 22.04 LTS for now. Node.js 20/22 and some OpenClaw native dependencies have been more rigorously tested on 22.04. ## 3. SSH Access You can access your VPS via Hostinger's browser terminal, but it is highly recommended to use a native terminal (like Windows Terminal, macOS Terminal, or PuTTY). To find your IP: 1. Go to your VPS Dashboard in hPanel. 2. Look for the **VPS IP** block (e.g., `193.168.1.100`). Open your terminal and connect: ```bash ssh root@193.168.1.100 ``` *(Enter the root password you created during OS selection).* Once logged in, **immediately** follow the [Fresh Ubuntu VPS Setup](/guides/fresh-ubuntu-vps-setup) guide to create a non-root user. Running OpenClaw as `root` is a major security risk. ## 4. Hostinger's Built-in Firewall Hostinger provides a hardware-level firewall through hPanel, which sits in front of your Ubuntu VPS. If you enable Hostinger's firewall, it will block all traffic by default except SSH. 1. Go to **VPS** -> **Manage** -> **Security** -> **Firewall**. 2. Click **Create firewall configuration**. 3. Add a rule to **ALLOW** SSH (Port `22`). 4. Add a rule to **ALLOW** HTTP (Port `80`) and HTTPS (Port `443`) if you plan to use a reverse proxy like Caddy or Nginx for your webhooks. > [!NOTE] Do **not** add a rule allowing port `18789`. Your OpenClaw Gateway should remain private. Connect to it via an SSH Tunnel or Tailscale instead. ## 5. IPv6 Considerations Hostinger often assigns an IPv6 address alongside your IPv4 address. If your DNS is routed via Cloudflare or another proxy, ensure you are not accidentally exposing your Gateway over the IPv6 interface. By default, the safest route is to bind OpenClaw strictly to `127.0.0.1` or a Tailscale IP (`100.x.x.x`), which ignores the public IPv6 assignment entirely. --- ### Performing an OpenClaw Security Audit URL: https://www.clawready.in/guides/openclaw-security-audit/ Description: A comprehensive checklist and workflow for conducting a security audit of your OpenClaw setup, including using openclaw doctor and manual server checks. > [!NOTE] An audit should be performed *after* completing your installation and before pushing any OpenClaw instances into a production state (e.g., handling real business logic or customer data). Auditing your OpenClaw setup ensures that there are no unsafe defaults lingering on your VPS. This guide combines the automated `openclaw doctor` checks with manual network verification to give you a complete picture of your security posture. ## 1. Automated Health Check OpenClaw ships with a built-in diagnostic tool. SSH into your VPS and navigate to the directory where your OpenClaw `.env` file lives. **How to read the output:** - **[OK]**: The configuration is safe and expected. - **[WARN]**: The configuration is potentially unsafe depending on context (e.g. `0.0.0.0` might be okay if placed behind a strictly configured Reverse Proxy, but highly unsafe if port 18789 is open). - **[FAIL]**: Critical misconfiguration that must be fixed immediately. > [!NOTE] Do not paste the raw output of `openclaw doctor` into public GitHub issues or forums! It may contain excerpts of tokens or your VPS IP address. Always redact sensitive information before asking for help. ## 2. Manual Network Exposure Check The most critical part of the audit is verifying your network exposure. `openclaw doctor` only checks application configuration, not your VPS firewall. Run this command to check what ports are actively listening to the public internet: Look for the OpenClaw Gateway port (usually `18789`). **Unsafe Output:** If the Local Address is `*:18789` or `0.0.0.0:18789`, the Gateway is exposed to the entire internet! **Safe Output (Tailscale/Localhost):** If the Local Address is your Tailscale IP (`100.x.x.x`) or Localhost (`127.0.0.1`), the Gateway is protected. ## 3. Firewall (UFW) Verification If you are using Ubuntu, check your Uncomplicated Firewall (UFW) status to ensure the port isn't explicitly opened. If you see `18789/tcp ALLOW Anywhere`, run `sudo ufw delete allow 18789/tcp` immediately. ## 4. Token & Secrets Audit Review your `.env` file manually. Look for the following issues: 1. **Hardcoded API Keys in code:** Ensure all LLM provider keys (OpenAI, Anthropic) and messaging tokens (Telegram, WhatsApp) are ONLY located in `.env`, not hardcoded in custom scripts or agents. 2. **File permissions:** Your `.env` file should not be readable by other users on the server. Enforce strict permissions on your `.env`: This ensures only the owner (the user running OpenClaw) can read or write to the file. ## 5. Channel Security (Telegram/WhatsApp) If you are using Telegram, verify your `dmPolicy` in your `.env`. It should be set to `strict` or `allowlist`. If it is missing or set to `public`, anyone who finds your bot on Telegram can talk to your OpenClaw instance and execute tools! For WhatsApp, ensure you are using a dedicated number (not your personal phone number) to prevent personal messages from being ingested by the AI. ## Remediation If any part of this audit failed, stop your Gateway immediately (`pm2 stop openclaw-gateway`), apply the fixes, and run the audit again before bringing the system back online. --- ### Tailscale Private Access Setup for OpenClaw URL: https://www.clawready.in/guides/openclaw-tailscale-setup/ Description: Use a Tailscale private network to safely access the OpenClaw Gateway from your laptop without exposing port 18789 to the public internet. > [!NOTE] This guide prevents your Gateway from being exposed publicly. Do not share your Tailscale auth keys or invite untrusted users to your Tailnet. Anyone on your Tailnet can reach your Gateway. Tailscale lets you create a secure, private network (a "Tailnet") between your laptop and your VPS. Once set up, you can access the OpenClaw Gateway dashboard securely without opening port `18789` on your firewall. In India, where ISPs often use CGNAT or dynamic IPs, Tailscale is much more reliable and easier to configure than a traditional IP whitelist. ## 1. Install Tailscale on your Laptop Before configuring the VPS, install Tailscale on your local computer (the one you'll use to view the dashboard). 1. Create a free account at [Tailscale.com](https://tailscale.com). 2. Download and install the Tailscale client for your OS (Windows, macOS, or Linux). 3. Log in to the app. Your laptop is now part of your private Tailnet. ## 2. Install Tailscale on your VPS SSH into your Ubuntu VPS. Run the official Tailscale installation script: Once installed, start Tailscale and authenticate your server: Copy the URL from your terminal output, paste it into your laptop's browser, and log in. Your VPS is now securely connected to your Tailnet. ## 3. Find your VPS's Tailscale IP Every device on your Tailnet gets a static IP address starting with `100.x.x.x`. You need the VPS's Tailscale IP to access the Gateway. Run this command on the VPS: Note this IP down. We'll refer to it as `100.x.x.x` in the next steps. > [!NOTE] Unlike cloud providers that charge $4–$5/month for a static IPv4 address, your Tailscale IP (`100.x.x.x`) is completely free and never changes, making it perfect for bookmarks. ## 4. Bind OpenClaw Gateway to Tailscale By default, OpenClaw Gateway might be binding to `localhost` (`127.0.0.1`) or all interfaces (`0.0.0.0`). If it's on `127.0.0.1`, you can't reach it from your laptop (even with Tailscale). If it's on `0.0.0.0`, it's listening to the public internet (which is dangerous). We need to tell OpenClaw to listen **only** on the Tailscale IP. Open your `.env` file where OpenClaw is running: Ensure you have the host configuration set to your Tailscale IP: *(Replace `100.x.x.x` with the IP you got in Step 3).* Save the file and restart your Gateway: ## 5. Verify the Connection On your laptop, make sure Tailscale is running and connected. Open your web browser and navigate to: `http://100.x.x.x:18789` You should now see the OpenClaw Gateway dashboard! > [!NOTE] To be absolutely certain you aren't exposed to the public web, find your VPS's **public** IP address and try visiting `http://:18789`. It should fail to load (timeout or connection refused). If it loads, your firewall is not configured correctly. ## Troubleshooting - **Page won't load:** Ensure Tailscale says "Connected" on your laptop's menu bar/system tray. - **Connection refused:** Run `sudo ss -tlnp | grep 18789` on the VPS. Ensure it shows the `100.x.x.x` IP and not `127.0.0.1`. - **Can't ping VPS:** By default, Tailscale blocks pings if UFW is running strictly. Tailscale traffic bypasses UFW by default, but if you've locked down `tailscale0` interfaces, you may need to allow it: `sudo ufw allow in on tailscale0`. --- ### OpenClaw Telegram Allowlist Guide URL: https://www.clawready.in/guides/openclaw-telegram-allowlist/ Description: How to configure Telegram allowlists in OpenClaw to explicitly limit which users or groups can execute commands. > [!NOTE] An allowlist is a static list of Telegram User IDs that are permanently granted access to your OpenClaw bot. Unlike Pairing, you don't need to generate temporary codes. This is the simplest and safest setup for a personal or small team bot. By default, creating a Telegram bot means anyone on Telegram can search for its username and message it. OpenClaw relies on **Direct Message Policies (`dmPolicy`)** and **Allowlists** to prevent unauthorized access. ## Understanding dmPolicy In your OpenClaw `.env` file, the `TELEGRAM_DM_POLICY` variable dictates how your bot responds to Direct Messages. There are three options: - `strict`: The bot ignores all messages from users not on the allowlist or without an active paired session. (Recommended). - `pairing`: The bot prompts unknown users to enter a pairing code. - `public`: **DANGEROUS.** The bot responds to everyone and allows anyone to execute tools. Never use this in production. For a personal bot, set your policy to `strict`: ## Configuring the Allowlist To let yourself bypass the `strict` policy, you must add your Telegram User ID to the allowlist. ### 1. Find your Telegram ID You need your numeric Telegram User ID (e.g., `123456789`), not your `@username`. You can find this by messaging `userinfobot` on Telegram. ### 2. Update the .env file Open your `.env` file and locate the `TELEGRAM_ALLOWLIST` variable. It expects a comma-separated list of User IDs. ### 3. Restart the Gateway For the changes to take effect, restart your OpenClaw Gateway: ## Group Chat Allowlists If you add your OpenClaw bot to a Telegram Group, the `dmPolicy` applies differently. By default, bots in groups only process messages that explicitly `@mention` them or start with a slash `/`. However, OpenClaw also supports a `TELEGRAM_GROUP_ALLOWLIST`. If you want the bot to only operate in specific groups (e.g., your company's internal dev chat), find the Group ID (which usually starts with a `-`, like `-100123456789`) and add it to your `.env`: > [!NOTE] If you allow a group, *anyone* in that group can trigger the bot by mentioning it. Ensure that every member of the allowed group is authorized to use the AI tools. ## Maintenance checklist - Review the allowed users in your `.env` file periodically. - Remove IDs for people who no longer need access (e.g., former employees or contractors). - Recheck your group allowlists after moving the bot into a new group to ensure you haven't accidentally granted access to a public chat. --- ### Understanding Telegram Pairing in OpenClaw URL: https://www.clawready.in/guides/openclaw-telegram-pairing/ Description: A complete guide to the Telegram pairing flow: how to generate codes, manage expiry, and securely grant access to your bot. > [!NOTE] When you create a Telegram bot, anyone on the internet can search for its username and send it a message. "Pairing" is OpenClaw's security mechanism to verify that the person talking to the bot is actually authorized by the admin. Without pairing or an allowlist, your OpenClaw instance would execute agent tasks for random strangers. Pairing ensures that only trusted users are given a session. ## The Pairing Flow If your `DM_POLICY` is set to `strict` or `pairing`, a new user messaging your bot will receive a generic welcome message or a prompt asking for a pairing code. To grant them access, you (the admin with CLI access to the OpenClaw Gateway) must generate a pairing code. ### 1. Generating a Code SSH into your VPS and navigate to your OpenClaw directory. Run the CLI tool to generate a new pairing ticket: ### 2. Redeeming the Code Provide the `849-291` code to the user. They must send it to the Telegram bot as a message. **User to Bot:** > `/pair 849-291` If successful, the bot will reply confirming the pairing, and a secure session is established. ## Code Expiry & Security > [!NOTE] Never share pairing codes in public chats, screenshots, GitHub issues, or community posts. A pairing code acts as a temporary password to access your AI instance. - **Short-Lived:** Pairing codes expire quickly (usually 15 minutes). If the user misses the window, you must generate a new one. - **Single-Use:** Once a code is successfully redeemed by a Telegram user ID, it cannot be used again by anyone else. - **Session Revocation:** If you need to kick a user out, you can revoke their session via the Gateway dashboard or the CLI: ## When to use Pairing vs Allowlist - **Pairing** is best for dynamic teams or client onboarding, where you don't know their Telegram User ID beforehand. You generate a code on demand. - **Allowlisting** is best for static setups (like your own personal bot). You hardcode your Telegram User ID into the `.env` file, bypassing the need to pair entirely. If you're setting up a bot just for yourself, skip pairing and use an Allowlist. Read the [Telegram Allowlist guide](/guides/openclaw-telegram-allowlist) for more details. --- ### OpenClaw Telegram Channel Setup URL: https://www.clawready.in/guides/openclaw-telegram-setup/ Description: How to connect a Telegram bot to your OpenClaw Gateway using BotFather. Covers token handling, allowlists for safe access, and verifying the connection. ## Short answer To connect Telegram to OpenClaw: 1. Talk to `@BotFather` on Telegram to create a bot and get an API token. 2. Add the token to your OpenClaw `.env` file (`TELEGRAM_TOKEN=123...`). 3. Configure the `TELEGRAM_ALLOWLIST` in the dashboard or `.env` so only you can talk to the bot. 4. Restart the Gateway. ## When is Telegram the right channel? Telegram is the recommended first channel for OpenClaw users, especially in India, because: - **It is free and instant:** No API approval processes (unlike WhatsApp Business). - **It has built-in security:** You can easily restrict access using Telegram User IDs. - **It handles rich media:** Sending images, files, and code blocks works cleanly. - **No phone number exposure:** You do not need a dedicated SIM card to run a Telegram bot. If you are building an internal tool, a personal assistant, or testing a concept, start with Telegram. ## Step 1: Create the Bot via BotFather BotFather is the official Telegram bot that creates other bots. 1. Open Telegram and search for `@BotFather` (look for the verified blue tick). 2. Send the message `/newbot`. 3. Give your bot a **name** (e.g., "My OpenClaw Agent"). This is what users see. 4. Give your bot a **username** (e.g., `my_claw_agent_bot`). This must end in "bot" and must be globally unique. 5. BotFather will reply with a long string of characters. This is your **HTTP API Token**. Your token looks like this: `1234567890:ABCdefGhIJKlmNoPQRstuVwXyz`. Anyone with this token can read messages sent to your bot and impersonate it. Never paste this token into a public forum, GitHub issue, or support chat. ## Step 2: Add the token to your OpenClaw workspace You must inject the token into the Gateway's environment. The safest way to do this is via the `.env` file. SSH into your VPS and open your OpenClaw workspace: Open the `.env` file in a text editor like `nano`: Add or update the Telegram token line. Make sure there are **no spaces** around the equals sign: ```ini TELEGRAM_TOKEN=1234567890:ABCdefGhIJKlmNoPQRstuVwXyz ``` Save and exit (`Ctrl+O`, `Enter`, `Ctrl+X`). ## Step 3: Configure the Allowlist (Critical) By default, any Telegram user who finds your bot's username can send it messages. If your agent has tools enabled (like web search or shell execution), a random user could use your API credits or execute commands on your server. You **must** configure an allowlist. 1. Find your personal Telegram User ID. You can do this by messaging a bot like `@userinfobot`. It will reply with a numeric ID (e.g., `987654321`). 2. Open your `.env` file again. 3. Add the allowlist variable, using your User ID: ```ini TELEGRAM_ALLOWLIST=987654321 ``` If you want to allow multiple users, separate their IDs with commas (no spaces): `TELEGRAM_ALLOWLIST=987654321,112233445` ## Step 4: Restart the Gateway and Verify For the `.env` changes to take effect, you must restart the OpenClaw Gateway. If you are running manually: If you are using PM2: **Verification:** 1. Open Telegram and search for your bot's username. 2. Click **Start** or send a message like "Hello". 3. If everything is configured correctly, OpenClaw should receive the message, send it to the AI model, and reply to you in Telegram. ## Common Mistakes - **Spaces in the `.env` file:** Writing `TELEGRAM_TOKEN = 123...` (with spaces) will break the configuration. - **Using `@username` for the allowlist:** The allowlist requires the numeric User ID, not your text `@handle`. - **Forgetting to restart:** Changes to `.env` never apply until the Gateway process restarts. - **Bot Privacy Mode:** By default, Telegram bots cannot read messages in group chats unless they are mentioned. If you add your bot to a group, you must use `/setprivacy` in BotFather to disable privacy mode. ## Token Rotation If you accidentally share your token, or if you suspect your server was compromised, you must rotate the token immediately. 1. Go to `@BotFather` in Telegram. 2. Send `/revoke`. 3. Select your bot. 4. BotFather will issue a new token and invalidate the old one. 5. Update your `.env` file with the new token. 6. Restart the OpenClaw Gateway. ## What not to do - **Do not hardcode the token** into any custom scripts. Always read from environment variables. - **Do not commit `.env` to Git.** If you are tracking your workspace with Git, ensure `.env` is in your `.gitignore` file. - **Do not disable the allowlist** if your agent has file access or shell execution tools enabled. ## Bot not replying? If you send a message and the bot ignores you, check the [Telegram Bot Not Replying](/troubleshooting/telegram-bot-not-replying) troubleshooting guide to diagnose webhook vs polling issues, API key failures, and log inspection. **Redaction Warning:** If you ask for help in the community or via [Setup Help](/setup-help), do not share your raw Telegram token or unredacted `.env` file. Replace sensitive data with `XXX`. --- ### OpenClaw VPS Security Checklist URL: https://www.clawready.in/guides/openclaw-vps-security-checklist/ Description: The mandatory security hardening checklist for your Ubuntu VPS before you connect OpenClaw to the internet. Covers SSH keys, UFW, non-root users, and secret management. ## Why this checklist is mandatory When you install OpenClaw, you are deploying an agent that can read files, execute code, and spend your API credits. It connects to external messaging channels. If a bot or automated scanner compromises your VPS, they don't just get an empty server — they get access to your AI infrastructure, your bot tokens, and your billing accounts. This checklist covers the absolute minimum hardening required for an internet-facing OpenClaw server. --- ## Phase 1: Access Control ### 1. Disable Root Login You should never log in as `root`. You should log in as a standard user with `sudo` privileges. - Open `/etc/ssh/sshd_config` - Set `PermitRootLogin no` - Restart SSH: `sudo systemctl restart ssh` ### 2. Disable Password Authentication Passwords can be brute-forced. SSH keys cannot. - Ensure your SSH public key is in `~/.ssh/authorized_keys` for your non-root user. - Open `/etc/ssh/sshd_config` - Set `PasswordAuthentication no` - Restart SSH: `sudo systemctl restart ssh` > [!NOTE] Keep your current SSH session open. Open a **second** terminal and verify you can log in with your SSH key. If you disable passwords and your key isn't working, you will be locked out of your server. --- ## Phase 2: Firewall (UFW) Your server must drop all incoming traffic by default, except for SSH. ### 3. Configure UFW Rules Check current status: If it is inactive, set the default policies and allow SSH: Enable the firewall: You might be tempted to open port 18789 so you can view the dashboard. **Do not do this.** It exposes your OpenClaw Gateway to the internet. Access the dashboard via an SSH tunnel or Tailscale instead. ### 4. Verify Gateway Binding Even with a firewall, defense-in-depth requires that the Gateway process itself does not listen on the public network interface. Run: Ensure the output shows `127.0.0.1:18789` (or a Tailscale IP), and **not** `0.0.0.0:18789`. If it says `0.0.0.0`, open your `.env` file, set `OPENCLAW_HOST=127.0.0.1`, and restart the Gateway. --- ## Phase 3: Secret Management ### 5. Protect the `.env` File Your `.env` file contains your AI model API keys and channel tokens. It must be locked down. Navigate to your workspace and restrict permissions: ### 6. Do Not Commit Secrets If you use Git to backup or version your workspace, ensure `.env` is in your `.gitignore` file. If you accidentally commit an API key to a public GitHub repo, it will be scraped and used within seconds. --- ## Phase 4: System Hygiene ### 7. Install Fail2Ban (Optional but Recommended) Fail2Ban automatically blocks IP addresses that fail SSH logins too many times. ### 8. Enable Unattended Upgrades Keep your Ubuntu server patched automatically for security updates. --- ## Phase 5: OpenClaw Specifics ### 9. Configure Channel Allowlists Do not leave your Telegram or WhatsApp bots open to the public unless that is explicitly your product. Configure `TELEGRAM_ALLOWLIST` in your `.env` file using your numeric User ID. ### 10. Audit Tool Permissions If your agent does not need to execute shell commands, do not enable the shell execution tool. If it does not need to write files, restrict it to read-only. Grant the principle of least privilege. --- ## Monthly Maintenance Checklist Set a calendar reminder to do this once a month: - SSH into the server and run `sudo apt update && sudo apt upgrade -y` - Check Gateway logs for unusual activity (`pm2 logs openclaw`) - Reboot the server (`sudo reboot`) to ensure PM2 and the Gateway recover automatically. - Check billing limits on your Anthropic/OpenAI accounts to ensure no unexpected spikes. ## What not to do - **Do not use `chmod 777`** on your workspace folder to fix "permission denied" errors. Use `chown` to fix the owner instead. - **Do not post unredacted logs.** If you ask for help, replace IPs and tokens with `XXX`. - **Do not share your root password** with anyone offering to "fix it for you." ## When to ask for help If you are unsure whether your firewall is configured correctly, or if you suspect your server has been compromised, ask for a Security Audit via the [Setup Help](/setup-help) service. We can review redacted `ss` and `ufw` outputs to verify your posture. --- ### OpenClaw WhatsApp Setup for Indian Users URL: https://www.clawready.in/guides/openclaw-whatsapp-setup/ Description: Set up OpenClaw with WhatsApp using dedicated-number guidance, QR/session warnings, privacy risks, and safer group boundaries. ## Who this is for This guide is for developers building OpenClaw assistants meant to interact over WhatsApp. In India, WhatsApp is the default communication layer, meaning the stakes for account bans or privacy leaks are extremely high. > [!NOTE] By scanning the QR code, your OpenClaw agent gains the ability to read every single message sent to that number. Using your primary personal number exposes your family, friends, and OTPs to the agent. **Always use a secondary, dedicated device or virtual number.** ## Prerequisites - OpenClaw installed and Gateway running. - A secondary phone or a virtual number dedicated solely to this bot. - A clean WhatsApp Business account installed on that secondary device. ## Setup Steps
  1. ### Prepare the dedicated device Ensure your dedicated WhatsApp Business number is active and can receive messages.
  2. ### Add the WhatsApp Channel Use the OpenClaw CLI to initiate the WhatsApp connection process. This will generate a QR code in your terminal.
  3. ### Scan the QR Code Open WhatsApp Business on your dedicated device. Go to **Linked Devices** and scan the QR code printed in your terminal. > [!NOTE] Scanning the QR code generates session files inside your OpenClaw workspace. These files are the equivalent of your WhatsApp password. **Never commit them to GitHub.**
  4. ### Configure Allowlist Security OpenClaw will now reply to anyone who messages that number. To prevent spam and API abuse, edit your `claw.config.json`. ```json "channels": { "whatsapp": { "enabled": true, "dmPolicy": "allowlist", "allowlist": ["919876543210"] } } ``` *(Replace with your actual personal number, including the country code without the `+`)*
  5. ### Restart the Gateway Restart OpenClaw to enforce the allowlist.
## Group Boundaries & Bad Output - **Spam Bans:** WhatsApp will ban numbers that send too many messages quickly or receive user reports. Your OpenClaw agent should never send unprompted outbound messages. - **Group Exposure:** If you add your bot to a family or business group, it will read *every* message if configured poorly. Ensure `groupPolicy` is set to `mentions_only`. ## Rollback & Disconnect To disconnect the bot, simply log out of the "Linked Device" from your phone, and run: ## When to ask for help WhatsApp API setups (via Meta) versus WhatsApp Web bridging (via Baileys/Puppeteer) have drastically different ban risks and scaling limits. If you need to deploy this for a production business in India without risking a ban, request a [WhatsApp Architecture Review](/setup-help). ## Sources - OpenClaw Docs - WhatsApp Integration: [https://docs.openclaw.ai/channels/whatsapp](https://docs.openclaw.ai/channels/whatsapp) (Checked on 2026-06-03) - WhatsApp Business Policy: [https://www.whatsapp.com/legal/business-policy](https://www.whatsapp.com/legal/business-policy) (Checked on 2026-06-03) --- ### Run OpenClaw After SSH Logout (PM2) URL: https://www.clawready.in/guides/run-openclaw-after-logout/ Description: How to use PM2 to keep your OpenClaw Gateway running 24/7 in the background after you close your laptop or disconnect from the VPS. ## Short answer If you start OpenClaw using `npx openclaw start` and then close your terminal, the process dies. To keep it running permanently, install a process manager called **PM2**. ## Why processes stop after logout When you connect to your VPS via SSH, Linux starts a new "session." Any program you start in the terminal (like `npx openclaw start`) is attached to that session. When you disconnect or close your laptop, Linux ends the session and kills all attached programs. To prevent this, you need a process manager. It runs in the background (as a "daemon"), detaches your programs from the SSH session, and restarts them automatically if they crash. For Node.js applications like OpenClaw, **PM2** is the industry standard. (Systemd is also an option, but PM2 is much easier for beginners and handles Node logs gracefully). ## Step 1: Install PM2 First, stop your currently running Gateway if it is running in your terminal (`Ctrl+C`). Next, install PM2 globally using `npm`: Verify PM2 is installed: ## Step 2: Start the Gateway with PM2 Navigate to your OpenClaw workspace directory (where your `.env` and `database.sqlite` live): Start the OpenClaw Gateway using PM2. We will name the process "openclaw" to make it easy to remember: You should see a table appear showing the process status: > [!NOTE] If the status says `errored` or `stopped`, the Gateway failed to start. Run `pm2 logs openclaw` to see the error, and check the [Gateway Not Running](/troubleshooting/gateway-not-running) guide. ## Step 3: Enable startup persistence (Reboot survival) Right now, PM2 keeps OpenClaw running when you close your laptop. But if the VPS itself restarts (e.g., your hosting provider performs maintenance), PM2 will not start automatically. To make PM2 start on server boot, run: PM2 will print a command that looks something like this: `sudo env PATH=$PATH:/home/clawuser/.nvm/... pm2 startup systemd -u clawuser --hp /home/clawuser` **Copy the command PM2 gives you, and run it in your terminal.** Finally, save the current PM2 process list so it remembers to start OpenClaw: ## Step 4: The Reboot Test The best way to know if your setup is robust is to test it. 1. Reboot your server: 2. Wait 2 minutes for the server to come back online. 3. SSH back into your server. 4. Check PM2 status: If OpenClaw shows as `online`, your setup is complete. It will run 24/7. ## Essential PM2 commands You will use these commands frequently when managing your Gateway. | Task | Command | |------|---------| | View status of all apps | `pm2 status` | | View live logs | `pm2 logs openclaw` | | Restart the Gateway | `pm2 restart openclaw` | | Stop the Gateway | `pm2 stop openclaw` | | View detailed app info | `pm2 show openclaw` | ## Log inspection Because the Gateway is running in the background, you will not see errors printed to your screen automatically. If your bot stops replying, your first step should always be checking the logs: ## Rollback: How to remove the PM2 process If you want to stop running OpenClaw in the background and return to manual starts: 1. Stop the process: 2. Delete it from PM2's list: 3. Save the empty list so it doesn't try to start on reboot: ## What not to do - **Do not run PM2 as `root`.** Always run it as your normal user. Running PM2 as root means OpenClaw runs as root, which is a massive security risk. - **Do not use `screen` or `tmux` instead of PM2.** While those tools keep the session alive, they do not automatically restart the Gateway if it crashes, nor do they handle server reboots cleanly. Use PM2. --- ### What Is OpenClaw? URL: https://www.clawready.in/guides/what-is-openclaw/ Description: A field-manual explanation of OpenClaw ## Short answer OpenClaw is a self-hosted agent runtime. You install it on a server (usually a VPS), and it connects AI models (like Claude or GPT) to messaging channels (like Telegram or WhatsApp) and tools (like file access or web search). The central process that coordinates everything is called the **Gateway**. If you are here because you want to set up OpenClaw, start by understanding the moving parts below, then follow the [recommended beginner path](/start-here). ## Who this is for This guide is for anyone who has heard about OpenClaw but is not yet clear on: - What the Gateway actually does - How channels, models, and tools connect - What "self-hosted" means in practice - Why security is not optional - What risks come with running an agent that has real tool access ## The four main components ### 1. Gateway The Gateway is the core server process. It is a Node.js application that runs on your [VPS](/glossary/vps) and listens on [port 18789](/glossary/port) by default. The Gateway: - Receives incoming messages from connected channels - Routes messages to the configured AI model - Executes tool calls requested by the model - Serves the web dashboard for monitoring and configuration - Manages authentication, channel state, and session persistence If the Gateway stops, everything stops — no messages are processed, no tools execute, and the dashboard becomes unreachable. > [!NOTE] Unlike a blog or a public API, the Gateway has direct access to your AI model credentials, messaging channel tokens, and any tools you enable (including shell execution). Treat Gateway security like you would treat SSH access to a production server. ### 2. Channels A channel is a messaging platform that connects to the Gateway. OpenClaw supports multiple channels: - **Telegram** — the most common for Indian builders. Uses BotFather tokens and supports allowlist-based access control. - **WhatsApp** — requires a phone number and QR-code session. Carries additional privacy risks because of personal contact access. - **Web dashboard** — a browser-based interface served by the Gateway itself. - **Other channels** — Discord, Slack, Matrix, and more depending on your configuration. Each channel uses a **token** or **session** to authenticate with the Gateway. If these tokens are leaked, someone else can impersonate your bot or read your messages. ### 3. Models Models are the AI providers that power the agent's reasoning. OpenClaw connects to providers like: - Anthropic (Claude) - OpenAI (GPT) - Local models via Ollama or similar Each provider requires an **API key** stored in your server's environment file (`.env`). These keys are billed — if someone gains access to your Gateway and your API key, they can consume your credits. ### 4. Tools Tools are capabilities that the agent can use. Examples include: - File system access (read, write, delete files on your server) - Shell command execution - Web search - API calls to external services - Database queries Tools are the highest-risk component. A misconfigured tool permission can allow the agent (or anyone who can send it messages) to execute arbitrary commands on your server. > [!NOTE] If you enable file system access or shell execution, the agent can modify your server. Review tool permissions carefully before connecting any public-facing channel. ## How the pieces connect ``` ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ │ Telegram │────▶│ │────▶│ AI Model │ │ WhatsApp │ │ Gateway │ │ (Claude, │ │ Dashboard │◀────│ :18789 │◀────│ GPT, etc.) │ └─────────────┘ │ │ └──────────────┘ │ │ │ │────▶ Tools (files, │ │◀──── shell, APIs) └─────────────┘ ``` 1. A message arrives from a channel (e.g., Telegram). 2. The Gateway receives it and sends it to the configured AI model. 3. The model responds, possibly requesting tool calls. 4. The Gateway executes the tools and returns results to the model. 5. The final response is sent back through the channel. ## What "self-hosted" means OpenClaw runs on **your** server. Unlike a SaaS product: - **You** manage the VPS, its operating system, its firewall, and its updates. - **You** store the API keys, bot tokens, and session data. - **You** decide who can access the Gateway and what tools the agent can use. - **You** are responsible for security — there is no hosted backend protecting you. This gives you full control and full responsibility. ## Security posture summary | Component | Risk if compromised | Key protection | |-----------|-------------------|----------------| | Gateway process | Full system access | Bind to localhost, use SSH tunnel or Tailscale | | Channel tokens | Bot impersonation, message interception | Store in `.env` with `chmod 600`, never commit to Git | | API keys | Financial loss (credit consumption) | Same as tokens — `.env` with strict permissions | | Tool permissions | Arbitrary command execution on server | Review and restrict before connecting public channels | | Dashboard | Config and log exposure | Access via SSH tunnel only — never expose publicly | ## Common misconceptions **"OpenClaw is just a chatbot."** — No. It is an agent with tool access. A chatbot replies to messages. An agent can read files, execute commands, make API calls, and modify your server. **"I need to open port 18789 to use the dashboard."** — No. Use an [SSH tunnel](/glossary/ssh) or [Tailscale](/guides/openclaw-tailscale-setup) for private access. Opening the port exposes your Gateway to the internet. **"Running `ufw allow 18789` is a quick fix."** — It is a quick way to expose your entire AI infrastructure to public internet scanners. See the [port 18789 guide](/guides/openclaw-gateway-port-18789) for safe alternatives. **"I can use my personal WhatsApp number safely."** — Using a personal number means the agent may process your private contacts' messages. Use a [dedicated WhatsApp number](/guides/dedicated-whatsapp-number-openclaw) instead. ## What not to do - Do not install or run OpenClaw as the `root` user. - Do not bind the Gateway to `0.0.0.0` unless you understand TLS, auth, and reverse proxy hardening. - Do not share bot tokens, API keys, or session data in public forums, screenshots, or GitHub issues. - Do not enable shell execution tools on a bot with open DM access. - Do not skip the [VPS security checklist](/guides/openclaw-vps-security-checklist) before connecting channels. ## Next steps 1. Read the [Start Here](/start-here) page for the recommended beginner path. 2. If you already have a VPS, go to [Fresh Ubuntu VPS Setup](/guides/fresh-ubuntu-vps-setup). 3. If you want to understand port 18789, read the [Gateway port guide](/guides/openclaw-gateway-port-18789). 4. If you want to check terms, browse the [Glossary](/glossary). ## When to ask for setup help If you are not sure whether your setup is safe, or if you are seeing errors you do not understand, use the [Setup Help](/setup-help) service. We can review your architecture using only redacted logs and high-level descriptions — we will never ask for raw API keys, bot tokens, WhatsApp session data, or root passwords. ## Sources - OpenClaw docs: [https://docs.openclaw.ai/](https://docs.openclaw.ai/) (Checked on 2026-06-23) - OpenClaw security docs: [https://docs.openclaw.ai/gateway/security](https://docs.openclaw.ai/gateway/security) (Checked on 2026-06-23) --- ## Collection: TROUBLESHOOTING ### Fix: OpenClaw Dashboard Not Opening URL: https://www.clawready.in/troubleshooting/dashboard-not-opening/ Description: Step-by-step diagnosis and fix for when the OpenClaw dashboard refuses to load. Covers SSH tunnels, Gateway binding, and firewall issues. ## The symptom You type `http://localhost:18789` or your server IP into your browser, and you see: - `ERR_CONNECTION_REFUSED` - `This site can't be reached` - A timeout or infinitely spinning loading wheel ## Quick diagnosis flow Follow these checks in order to isolate the problem. ### Check 1: Is the Gateway actually running? The dashboard is served by the OpenClaw Gateway. If the Gateway is crashed or stopped, the dashboard will not load. On your VPS, run: **Good output (Gateway is running):** **Empty output (Gateway is NOT running):** If the command returns absolutely nothing, the Gateway is not running. Go to the [Gateway Not Running](/troubleshooting/gateway-not-running) guide to fix the crash, then come back here. ### Check 2: Are you using the correct IP? Where are you trying to access the dashboard from? **Scenario A: Accessing from your laptop using an SSH tunnel (Recommended)** If you are typing `http://localhost:18789`, you **must** have an SSH tunnel running in a separate terminal on your laptop. - Command to run on your laptop: `ssh -L 18789:localhost:18789 clawuser@your_server_ip` - If you closed the terminal running the SSH tunnel, the connection drops. Re-run the command and leave the window open. **Scenario B: Accessing via Tailscale** If you are typing `http://100.x.y.z:18789`, verify that: - Tailscale is running on your laptop. - Tailscale is running on the VPS. - The Gateway is configured to bind to the Tailscale IP (check your `.env` for `OPENCLAW_HOST=100.x.y.z`). **Scenario C: Accessing via public VPS IP (Dangerous)** If you are typing `http://your_vps_public_ip:18789`, the connection is likely being blocked by your firewall (UFW or provider firewall). A connection refused error often means your firewall is **protecting you**. Running `sudo ufw allow 18789` or disabling UFW will expose your internal dashboard, logs, and connected AI models to anyone on the internet. Use an SSH tunnel instead — it is the correct fix. ### Check 3: Is the Gateway bound correctly? Look at the output from Check 1 again. Pay attention to the Local Address column. **If it says `127.0.0.1:18789`:** The Gateway is listening only for local connections. You must use an SSH tunnel. **If it says `0.0.0.0:18789` or `*:18789`:** The Gateway is listening on all interfaces. This is highly insecure unless you are behind a strict reverse proxy. Open your `.env` file, set `OPENCLAW_HOST=127.0.0.1`, and restart the Gateway. **If it says `::1:18789`:** The Gateway bound to IPv6 localhost instead of IPv4. This can break some SSH tunnel configurations. **Fix:** Explicitly define the IPv4 host in your `.env`: Then restart the Gateway. ### Check 4: Browser cache and DNS Sometimes the browser itself is confused, especially if you recently restarted tunnels. - Try opening `http://127.0.0.1:18789` instead of `localhost`. - Try an incognito / private browsing window. - Ensure you are using `http://` and not `https://` (unless you have explicitly configured a reverse proxy with TLS). ## Provider firewall panel warning If you are absolutely certain you configured a reverse proxy with TLS and authentication, and you are trying to access the dashboard securely from the outside, but it still times out: check your VPS provider's web-based firewall. Providers like AWS Lightsail, DigitalOcean, and Hetzner have cloud firewalls that exist outside of your server's UFW. If port 443 (for your proxy) is not allowed in the web panel, the traffic will never reach UFW. ## Bad fixes to avoid - **Do not run `sudo ufw allow 18789`** — this exposes your Gateway to the internet. - **Do not change OpenClaw config to `--host 0.0.0.0`** — same reason. - **Do not disable UFW** — this disables all firewall protections for your entire server. ## Prevention checklist - [ ] I am using an SSH tunnel or Tailscale to access the dashboard. - [ ] My Gateway is bound to `127.0.0.1` (or Tailscale IP). - [ ] My SSH tunnel terminal remains open while I browse. - [ ] The Gateway process is running (verified via `ss` or `pm2`). ## When to ask for help If the Gateway is running, the SSH tunnel is active, and the dashboard still refuses to load, there may be an obscure networking issue. Request assistance in the community or via [Setup Help](/setup-help). **Redaction Warning:** Before sharing screenshots of your terminal or `ss` output, blur out your public IP address and any tokens visible in your command history. Do not share your root password or unredacted `.env` files with anyone. --- ### Fix: Gateway Not Running URL: https://www.clawready.in/troubleshooting/gateway-not-running/ Description: Step-by-step diagnosis for Gateway crashes. Covers port conflicts, Node.js version issues, permission errors, and PM2 background failures. ## The symptom You try to use your Telegram or WhatsApp bot, but it does not reply. When you check your server, the OpenClaw Gateway is no longer running. Alternatively, when you try to start it, it crashes immediately with an error stack trace. ## Quick diagnosis flow The first step is figuring out *why* it stopped. The fix depends entirely on the error message. ### Check 1: Did it stop when you closed your laptop? If you started OpenClaw by running `npx openclaw start` and then closed your terminal or laptop, the process died. When you disconnect from an SSH session, Linux kills any programs running in that session. **The Fix:** You need a process manager like PM2 to run the Gateway in the background. See the [Run OpenClaw After Logout](/guides/run-openclaw-after-logout) guide. ### Check 2: Run it manually to see the error If PM2 says the process is stopped or "errored", stop PM2 and run the Gateway manually in the foreground. This forces the error to print directly to your screen. Watch the output closely. Compare what you see against the common failures below. --- ## Common crash errors ### 1. "EADDRINUSE: address already in use :::18789" **Meaning:** The Gateway cannot start because another program (or a duplicate/zombie Gateway process) is already listening on port 18789. **Diagnosis:** Find out what is using the port: **The Fix:** Kill the process holding the port. If the `ss` command shows `pid=1234`, run: Then try starting the Gateway again. ### 2. "SyntaxError" or "Unexpected token" immediately on boot **Meaning:** Your Node.js version is too old. OpenClaw requires modern JavaScript features. **Diagnosis:** Check your Node version: **The Fix:** If the output is v18 or lower, you must upgrade. Do not use Ubuntu's default `apt` package manager for this. Follow Step 1 in the [Install Guide](/guides/install-openclaw-ubuntu-vps) to install the latest LTS version using `nvm`. ### 3. "EACCES: permission denied" on `.env` or `database.sqlite` **Meaning:** The Gateway does not have the correct file permissions to read its configuration or write to its database. This almost always happens because you previously ran commands using `sudo` or as the `root` user. Running the Gateway as root to bypass permission errors is highly dangerous. It gives the agent total control over your server. Always fix the file ownership instead. **The Fix:** Change the ownership of your entire workspace back to your normal user: ### 4. Silent crash after channel config change **Meaning:** If you recently edited your `.env` file (e.g., adding a Telegram token or WhatsApp number) and the Gateway crashes silently, you may have introduced a syntax error in the `.env` file. **The Fix:** - Check for missing quotes around values with spaces. - Check for accidental line breaks in the middle of a token. - Ensure there are no spaces immediately before or after the `=` sign (e.g., `TELEGRAM_TOKEN=123...`, not `TELEGRAM_TOKEN = 123...`). ## Safe restart path Once you have identified and fixed the issue, verify the Gateway runs properly in the foreground: If it boots without errors and shows `Listening on 127.0.0.1:18789`, stop it with `Ctrl+C`, and restart it using PM2: ## Prevention checklist - [ ] I am running Node.js v20 LTS or higher. - [ ] I am using PM2 to keep the Gateway running in the background. - [ ] I never use `sudo` to run `npm` or `openclaw` commands. - [ ] My `.env` file is properly formatted. ## When to ask for help If the Gateway crashes with an obscure database error, a Node module missing error, or a channel API failure, you may need community assistance. Request help via the [Setup Help](/setup-help) service or community forum. **Redaction Warning:** When sharing crash logs, read through them carefully. The stack trace might contain your bot token, API keys, or VPS IP address. Redact these (replace with `XXX`) before posting the log. Never share your raw `.env` file. --- ### Fix OpenClaw Node Version Too Old URL: https://www.clawready.in/troubleshooting/node-version-too-old/ Description: Check your Node.js version, shell path, service path, and VPS runtime before reinstalling OpenClaw or changing Gateway access. OpenClaw install, `openclaw doctor`, or Gateway startup fails with a message like "Node.js version X is not supported. Requires v18 or higher." - Your interactive SSH shell uses one Node version, but the systemd service uses a different (older) binary - A Node version manager (nvm, fnm) works in SSH but is not loaded inside systemd - The VPS still has an old distro-packaged Node binary earlier in `PATH` - OpenClaw was installed before the expected runtime was configured Run these from the same user account that starts OpenClaw: ```bash node -v which node openclaw doctor ``` If OpenClaw runs through a service, check what binary the service actually uses: ```bash systemctl cat openclaw ``` **Good output:** **Bad output (old system Node):** 1. Confirm the Node.js version required by the current OpenClaw install guide (check [Node.js OpenClaw Setup](/guides/node-24-openclaw-setup)) 2. Install the required version using one consistent method (recommended: `nvm` or NodeSource PPA) 3. Restart your shell and confirm `node -v` again 4. If using systemd, update the service `ExecStart` path to use the full binary path: ```bash which node # Copy this path sudo systemctl edit openclaw ``` Then update `ExecStart` to use the absolute path to the correct `node` binary. 5. Restart OpenClaw and run `openclaw doctor` before changing any firewall or Gateway access settings > [!NOTE] Node.js version errors are local runtime problems. Opening port 18789 or disabling UFW will not fix a runtime issue — it will just expose a broken setup to the internet. ## When to ask for help Ask for help if `node -v` looks correct in SSH but OpenClaw still fails from systemd, PM2, or another process manager. Share only redacted logs and command output via [Setup Help](/setup-help). ## Sources - OpenClaw Docs: [https://docs.openclaw.ai/](https://docs.openclaw.ai/) (Checked on 2026-06-18) - NodeSource PPA: [https://github.com/nodesource/distributions](https://github.com/nodesource/distributions) (Checked on 2026-06-18) --- ### Fix Telegram Bot Not Replying in OpenClaw URL: https://www.clawready.in/troubleshooting/telegram-bot-not-replying/ Description: Check bot token, pairing, allowlist, dmPolicy, Gateway status, and logs without weakening access controls unnecessarily. You send a `/start` or normal text message to your Telegram bot. The message shows double checkmarks (delivered to Telegram), but the bot never replies — not even an error message. > [!NOTE] OpenClaw will silently ignore messages from users not on the `allowlist`. Before assuming something is broken, check your logs. A rejected message in the logs is a sign that your security configuration is correct. > [!NOTE] Never switch `dmPolicy` to `"open"` or `"all"` just to test if the bot responds. This allows internet scanners and unauthorized users to consume your LLM API credits. Fix the allowlist or pairing instead. 1. Your Telegram User ID is not on the `allowlist` — the bot is ignoring you for security reasons (correct behavior) 2. The bot token in `claw.config.json` is incorrect or expired 3. Another script or server is polling the same bot token, stealing messages from OpenClaw (Telegram 409 conflict) 4. OpenClaw Gateway is not running Watch the live Gateway logs while sending a test message from your phone: ```bash tail -f ~/openclaw-workspace/logs/gateway.log ``` Or via PM2: ```bash pm2 logs openclaw --lines 30 ``` **Good output (your allowlist policy is working):** This means the bot works perfectly — you just need to add your User ID to the allowlist. **Bad output (token conflict with another server):** ## What NOT to do **Do not open firewall rules for Telegram.** The default polling mode requires no incoming ports — Telegram reaches out to your server, not the other way around. ## When to ask for help If your token is correct, no other servers are running, and you still get zero logs, there may be a webhook/polling mismatch. Request a [Telegram Architecture Session](/setup-help). ## Sources - OpenClaw Docs - Telegram: [https://docs.openclaw.ai/channels/telegram](https://docs.openclaw.ai/channels/telegram) (Checked on 2026-06-18) - Telegram Bot API Docs: [https://core.telegram.org/bots/api](https://core.telegram.org/bots/api) (Checked on 2026-06-18) --- ## Collection: RECIPES ### OpenClaw Daily Briefing for Freelancers URL: https://www.clawready.in/recipes/freelancer-daily-briefing/ Description: A workflow for Indian freelancers who want an OpenClaw agent to prepare a daily morning briefing via Telegram. For independent consultants and freelancers, starting the day with a clear view of meetings, urgent emails, and pending tasks is crucial. Instead of checking 3 different apps, you can schedule an OpenClaw agent to fetch this data and send you a unified briefing on Telegram every morning at 8:30 AM. ## Tools Required To make this recipe work, your OpenClaw agent needs access to the following plugins: - `@openclaw/plugin-telegram` (for sending the message) - `@openclaw/plugin-gcal` (for fetching today's events) - `@openclaw/plugin-gmail` (for finding unread emails from specific clients) - `@openclaw/plugin-notion` (for reading your active To-Do list) > [!NOTE] Do not give the agent "write" or "delete" permissions to your Gmail or Notion unless you are an advanced user. Use Read-Only API scopes for your Calendar and Email to ensure a hallucination doesn't accidentally delete important client communication. ## 1. Agent Configuration Create a dedicated agent profile (e.g., `briefing-agent.json`) in your OpenClaw agents directory. ## 2. Automating the Briefing (Cron Job) OpenClaw supports executing agent workflows via its local API or CLI. You can use standard Linux `cron` on your VPS to trigger the briefing automatically. Open your crontab on the VPS: Add the following line to run the agent every morning at 8:30 AM IST (which is 03:00 AM UTC, assuming your server is on UTC time): *(The `1-5` ensures this only runs Monday through Friday).* ## 3. Expected Output At 8:30 AM, your OpenClaw Telegram bot will message you: ## Maintenance checklist - **Review tool scopes:** Ensure Gmail API tokens are restricted to read-only queries. - **Remove stale tokens:** If you stop using Notion, revoke the integration token from the Notion dashboard. - **Log Management:** `openclaw run` will save logs on your VPS. Clear them periodically so you don't run out of disk space. --- ### OpenClaw WhatsApp Lead Triage for Indian Small Businesses URL: https://www.clawready.in/recipes/whatsapp-lead-triage-india/ Description: A safety-first workflow outline for Indian small businesses that want OpenClaw to help triage WhatsApp lead messages without exposing personal chats or secrets. ## Business problem Many Indian small businesses receive leads through WhatsApp but lose track of who needs a callback, quotation, demo, payment reminder, or support follow-up. This workflow uses OpenClaw as a triage assistant, not as an unsupervised sales bot. ## Recommended boundary Use a dedicated WhatsApp number where possible. Do not casually connect your personal WhatsApp number, family groups, staff groups, or customer chats that contain private information. ## Workflow overview 1. Incoming messages arrive on a dedicated business number. 2. OpenClaw summarizes the lead request. 3. The lead is placed into a bucket such as new inquiry, quote needed, follow-up due, support issue, or ignore/spam. 4. A human reviews the bucket before sending business-critical replies. 5. Confirmed follow-ups are added to a lead sheet, CRM, or task list. ## Safety boundaries - Do not auto-reply to every WhatsApp message by default. - Do not include personal chats or unrelated groups. - Do not store WhatsApp session data in public repos, screenshots, or support forms. - Do not let the agent send payment, refund, legal, medical, or high-stakes commitments without human review. - Keep Gateway private through loopback, SSH tunnel, or a private network pattern. ## Setup steps 1. Run the readiness check before connecting WhatsApp. 2. Prepare the VPS and keep Gateway private. 3. Configure a dedicated WhatsApp number where possible. 4. Decide the lead buckets before enabling any automation. 5. Start with read-only summary and tagging. 6. Add human-approved follow-up actions only after testing. ## Good output vs bad output Good output is a short summary plus a conservative bucket, such as "new inquiry: wants website pricing, call tomorrow." Bad output is an automatic promise, a hallucinated price, a reply to the wrong group, or a summary that includes private data that should not be stored. ## Maintenance checklist - Review buckets weekly. - Rotate or remove unused tokens. - Check who can message the WhatsApp number. - Redact logs before asking for help. - Re-run the VPS security checklist after changing Gateway, channels, or tool permissions. ## When to ask for setup help Ask for help if you are not sure how to keep WhatsApp isolated from personal chats, how to keep Gateway private, or how to connect the lead sheet without exposing secrets. ## Sources - https://docs.openclaw.ai/ - https://docs.openclaw.ai/gateway/security - https://docs.openclaw.ai/gateway/remote --- ## Collection: GLOSSARY ### allowlist.mdx URL: https://www.clawready.in/glossary/allowlist/ ## What is an Allowlist? An **allowlist** (sometimes called a whitelist) is an access control mechanism. It works by establishing a strict rule: "Deny everyone by default, except for the specific people on this list." In the context of OpenClaw and Telegram, an allowlist is a list of numeric Telegram User IDs. ## Why it matters for OpenClaw Unlike a simple customer service chatbot, an OpenClaw agent is powerful. Depending on the tools you have enabled, the agent might be able to read files, modify your server, or spend your AI provider credits. If you connect a Telegram bot to OpenClaw, anyone on Telegram can search for your bot's username and send it a message. If you do not have an allowlist, the agent will process their message, potentially executing tools on their behalf. By configuring `TELEGRAM_ALLOWLIST` in your `.env` file, the Gateway checks the sender's User ID against the list before processing the message. If they are not on the list, the message is silently dropped. ## Common mistake **Using `@usernames` instead of numeric IDs.** When configuring the allowlist in OpenClaw, users often put their text username (e.g., `@clawbuilder`). This will not work. The Telegram API uses permanent numeric User IDs for authorization. Text usernames can be changed, making them insecure for access control. **Fix:** Use a bot like `@userinfobot` on Telegram to find your numeric ID (e.g., `123456789`), and use that in your `.env` file: `TELEGRAM_ALLOWLIST=123456789`. ## Related guides - [OpenClaw Telegram Channel Setup](/guides/openclaw-telegram-setup) - [OpenClaw VPS Security Checklist](/guides/openclaw-vps-security-checklist) --- ### api-key.mdx URL: https://www.clawready.in/glossary/api-key/ ## What is an API Key? An **API Key** is a long, randomly generated string of characters (e.g., `sk-ant-api03-abcdef1234567890...`). When a software application (like OpenClaw) makes a request over the internet to a service provider (like Anthropic or OpenAI), it includes the API key in the request. The provider checks the key to verify who is making the request, ensure they have permission, and track usage for billing purposes. ## Why it matters for OpenClaw OpenClaw is the engine, but the AI model is the brain. To get responses from Claude, GPT, or Gemini, OpenClaw must authenticate with those providers using API keys. You add these keys to your `.env` file (e.g., `ANTHROPIC_API_KEY=sk-ant-...`). Every time your agent answers a message or uses a tool, it consumes credits from your account balance. ## Common mistake **Failing to redact keys when asking for help.** When users run into a bug, they often copy-paste their terminal output, logs, or `.env` file into a public Discord channel, Telegram group, or GitHub issue. If an API key is included in that text, it is instantly compromised. **Fix:** Always read your logs before pasting them publicly. Replace sensitive data with `XXX` or `[REDACTED]`. If you ever suspect your key has been exposed, go to your AI provider's dashboard immediately and revoke/delete the key, then generate a new one. ## Related guides - [OpenClaw VPS Security Checklist](/guides/openclaw-vps-security-checklist) - [What is an Environment Variable?](/glossary/environment-variable) --- ### bot-token.mdx URL: https://www.clawready.in/glossary/bot-token/ ## What is a Bot Token? A **Bot Token** is a string of characters (e.g., `1234567890:ABCdefGhIJKlmNoPQRstuVwXyz`) that acts as a secure identifier and password for a messaging bot. When you create a bot on Telegram using `@BotFather`, it gives you this token. Any software that knows this token can connect to Telegram's servers and control that bot. ## Why it matters for OpenClaw To use OpenClaw via Telegram, the Gateway process needs to authenticate itself. You put the token in your `.env` file as `TELEGRAM_TOKEN`. When OpenClaw starts, it uses this token to tell Telegram: "I am this bot. Send any messages users send to me, and let me reply." ## Common mistake **Exposing the token publicly.** Just like API keys, bot tokens are highly sensitive. If a malicious actor gets your bot token, they can: - Read incoming messages from your users (compromising privacy). - Send spam or malicious links to your users from your bot's account. - Hook the bot up to their own agent. **Fix:** Never paste your token into public forums. Do not commit your `.env` file to Git. If your token is ever leaked, go back to `@BotFather` immediately, use the `/revoke` command to invalidate the old token, and generate a new one. ## Related guides - [OpenClaw Telegram Channel Setup](/guides/openclaw-telegram-setup) - [Telegram Bot Not Replying](/troubleshooting/telegram-bot-not-replying) - [What is an Environment Variable?](/glossary/environment-variable) --- ### environment-variable.mdx URL: https://www.clawready.in/glossary/environment-variable/ ## What is an Environment Variable? An **environment variable** is a value passed to a program by the operating system or the shell it runs in. Instead of hardcoding secrets (like passwords or API keys) directly into the source code of an application, developers use environment variables. In Node.js applications like OpenClaw, these variables are typically loaded from a plain text file named `.env` placed in the root directory of the workspace. ## Why it matters for OpenClaw The OpenClaw Gateway relies entirely on environment variables to know: - Where to listen (`OPENCLAW_HOST`) - What port to use (`OPENCLAW_PORT`) - How to authenticate with Telegram (`TELEGRAM_TOKEN`) - How to talk to Claude or ChatGPT (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) - Who is allowed to use the bot (`TELEGRAM_ALLOWLIST`) Because the `.env` file contains the "keys to the kingdom", it must be protected with strict file permissions. ## Common mistake **Committing `.env` to Git.** If you use version control (Git) to manage your workspace, you must ensure `.env` is listed in your `.gitignore` file. If you accidentally run `git add .` and push your `.env` file to a public repository (like GitHub), automated scrapers will find it immediately. Your API keys will be used by malicious actors, potentially costing you thousands of dollars in usage bills. **Fix:** Never commit `.env`. Also, protect it on your VPS by running `chmod 600 .env` so only the owner can read it. ## Related guides - [Install OpenClaw on Ubuntu VPS](/guides/install-openclaw-ubuntu-vps) - [OpenClaw VPS Security Checklist](/guides/openclaw-vps-security-checklist) --- ### firewall-ufw.mdx URL: https://www.clawready.in/glossary/firewall-ufw/ ## What is a Firewall (UFW)? A **firewall** acts as a barrier between your server and the public internet. It inspects all network traffic trying to enter or leave your server and blocks anything that hasn't been explicitly allowed. **UFW (Uncomplicated Firewall)** is a program included with Ubuntu that makes it easy to manage these rules. Instead of writing complex `iptables` commands, UFW lets you allow or block traffic with simple commands like `ufw allow 22` or `ufw deny 80`. ## Why it matters for OpenClaw When you run an OpenClaw Gateway on a VPS, it is connected to the internet 24/7. Automated bots and malicious scanners constantly probe every public IP address looking for open ports and vulnerable services. Your firewall is your first line of defense. A correctly configured UFW will block all incoming traffic by default, only allowing traffic on ports you specify (like port 22 for SSH). This means even if your OpenClaw Gateway accidentally binds to a public IP address, scanners cannot reach it. ## Common mistake **Running `sudo ufw allow 18789`.** When beginners cannot access the OpenClaw dashboard, they often assume the firewall is the problem and run `sudo ufw allow 18789`. This is a massive security risk. It opens port 18789 to the entire internet, allowing anyone to access your Gateway, view your logs, and potentially use your AI agent. **Fix:** Never open port 18789 on your firewall. If you need to access the dashboard, use an [SSH Tunnel](/glossary/ssh-tunnel) instead. If you must expose the Gateway publicly, do it through a secure [Reverse Proxy](/glossary/reverse-proxy) with TLS and authentication. ## Related guides - [OpenClaw VPS Security Checklist](/guides/openclaw-vps-security-checklist) - [Why Port 18789 Must Stay Private](/guides/openclaw-gateway-port-18789) - [Dashboard Not Opening](/troubleshooting/dashboard-not-opening) --- ### localhost.mdx URL: https://www.clawready.in/glossary/localhost/ ## What is Localhost? **Localhost** is the standard hostname given to the address of the local computer network interface. Its IP address is almost always `127.0.0.1`. When you tell a server application to "listen on localhost", you are telling it to only accept connections that originate from the same machine. ## Why it matters for OpenClaw When you start the OpenClaw Gateway, it needs to open a port (`18789`) to communicate. By default, it binds this port to localhost. This is a **security-first design**. Because the Gateway has access to your AI models, messaging channels, and potentially your server's file system, it should never be directly accessible from the public internet without strict protections. By binding to localhost, OpenClaw ensures that only someone who already has access to the VPS (like you, via SSH) can talk to the Gateway. ## Common mistake **Binding to 0.0.0.0 for convenience.** Many users get frustrated when they cannot open the OpenClaw dashboard in their laptop's web browser. They find a tutorial that tells them to change their `.env` file to `OPENCLAW_HOST=0.0.0.0` or run `openclaw start --host 0.0.0.0`. This is highly dangerous. `0.0.0.0` means "listen on all network interfaces," including the public internet. Anyone who guesses your VPS IP address can access your dashboard and use your agent. **Fix:** Keep the Gateway on `127.0.0.1` and use an [SSH Tunnel](/glossary/ssh-tunnel) or [Tailscale](/glossary/tailscale) to access it securely. ## Related guides - [Why Port 18789 Must Stay Private](/guides/openclaw-gateway-port-18789) - [Install OpenClaw on Ubuntu VPS](/guides/install-openclaw-ubuntu-vps) - [Dashboard Not Opening](/troubleshooting/dashboard-not-opening) --- ### pm2.mdx URL: https://www.clawready.in/glossary/pm2/ ## What is PM2? **PM2** is an advanced process manager for Node.js applications (like OpenClaw). It allows you to keep applications alive forever, reload them without downtime, and easily manage logging. Without a process manager, any program you start in an SSH terminal will be killed the moment you disconnect from the server. PM2 detaches the program from your SSH session and runs it as a background "daemon." ## Why it matters for OpenClaw For your Telegram or WhatsApp bot to reply at any time of day, the OpenClaw Gateway must be running 24/7. PM2 provides this continuous uptime. It also offers two critical features: 1. **Auto-restart on crash:** If OpenClaw encounters a fatal error and stops, PM2 will instantly restart it. 2. **Startup persistence:** You can configure PM2 to automatically start OpenClaw whenever your VPS boots up (like after a hosting provider maintenance window). ## Common mistake **Running PM2 as root.** Many beginners install PM2 globally using `sudo npm install -g pm2`, which is fine. However, they then run `pm2 start openclaw` while logged in as the `root` user. This means the OpenClaw Gateway process runs as root. If the Gateway runs as root, any shell execution tools enabled for the agent will also run as root. The agent (or anyone who exploits it) could wipe your server, change passwords, or install malware. **Fix:** Always log in as a standard user (e.g., `clawuser`) before running `pm2 start`. ## Related guides - [How to Keep OpenClaw Running After SSH Logout (PM2)](/guides/run-openclaw-after-logout) - [Gateway Not Running](/troubleshooting/gateway-not-running) --- ### port.mdx URL: https://www.clawready.in/glossary/port/ ## What is a port? A **port** is a numbered endpoint (ranging from 0 to 65535) that identifies a specific service running on a computer. Think of your server's IP address as a building address, and ports as apartment numbers inside that building. Each service listens on its own port number. Common ports: | Port | Service | |------|---------| | 22 | SSH (remote server access) | | 80 | HTTP (web traffic) | | 443 | HTTPS (encrypted web traffic) | | 18789 | OpenClaw Gateway (dashboard + API) | When you run a firewall command like `ufw allow 22`, you are telling the firewall to let incoming traffic reach port 22 (SSH). When you run `ufw allow 18789`, you are opening OpenClaw Gateway to the entire internet. ## Why it matters for OpenClaw OpenClaw Gateway listens on **port 18789** by default. This port serves the dashboard web interface, the internal API, and the connection layer for channels like Telegram and WhatsApp. By default, the Gateway binds to `127.0.0.1:18789` (localhost only), which means only processes running on the same server can reach it. This is the safe default. The danger comes when users change the binding to `0.0.0.0:18789` or open port 18789 in their firewall. This makes the Gateway reachable from any IP address on the internet. ## Common mistake **Opening port 18789 in UFW to access the dashboard from a browser.** Many beginners see `ERR_CONNECTION_REFUSED` and immediately run: ```bash # DO NOT run this — exposes Gateway to the public internet sudo ufw allow 18789 ``` This "fixes" the connection error but creates a critical security hole. Anyone who discovers your server's IP can now access your dashboard, read your conversations, and use your API keys. **Fix:** Use an SSH tunnel instead: ```bash ssh -L 18789:localhost:18789 clawuser@your_server_ip ``` Then access `http://localhost:18789` in your local browser. The traffic stays encrypted and private. ## Related guides - [OpenClaw Gateway Port 18789 Explained](/guides/openclaw-gateway-port-18789) - [OpenClaw VPS Security Checklist](/guides/openclaw-vps-security-checklist) - [Fix: Dashboard Not Opening](/troubleshooting/dashboard-not-opening) --- ### reverse-proxy.mdx URL: https://www.clawready.in/glossary/reverse-proxy/ ## What is a Reverse Proxy? A **reverse proxy** is a type of server that sits in front of other internal servers. When a user requests a web page, their browser connects to the reverse proxy. The reverse proxy then fetches the data from the internal server (like your OpenClaw Gateway) and sends it back to the user. Popular reverse proxy software includes **Nginx**, **Caddy**, and **Apache**. ## Why it matters for OpenClaw By default, the OpenClaw Gateway runs on `http://127.0.0.1:18789`. It is not designed to be exposed directly to the wild internet. It does not handle HTTPS (SSL certificates) natively, meaning if you expose it directly, all your traffic is unencrypted. If you want to access your dashboard from anywhere using a custom domain (e.g., `https://agent.mycompany.com`), you need a reverse proxy. The reverse proxy will: 1. Accept connections on standard ports (80 for HTTP, 443 for HTTPS). 2. Handle the SSL/TLS encryption so your traffic is secure. 3. Forward the decrypted request to the internal OpenClaw Gateway running safely on `127.0.0.1:18789`. 4. Add additional security measures, like basic authentication (passwords) or IP allowlisting. ## Common mistake **Exposing the Gateway directly instead of proxying.** Many users try to skip setting up Nginx. They simply change the Gateway to bind to `0.0.0.0` and open port `18789` in their firewall. This is extremely dangerous. It exposes your OpenClaw instance to the entire internet without HTTPS encryption, meaning anyone on your network (like a public Wi-Fi cafe) can intercept your session tokens and hijack your agent. **Fix:** If you need public access, learn how to configure Nginx or Caddy. If you just need personal access, use an [SSH Tunnel](/glossary/ssh-tunnel) or [Tailscale](/glossary/tailscale) instead — no reverse proxy required. ## Related guides - [Why Port 18789 Must Stay Private](/guides/openclaw-gateway-port-18789) - [OpenClaw VPS Security Checklist](/guides/openclaw-vps-security-checklist) --- ### ssh-tunnel.mdx URL: https://www.clawready.in/glossary/ssh-tunnel/ ## What is an SSH Tunnel? An **SSH Tunnel** (also known as SSH port forwarding) is a way to route local network traffic through an encrypted SSH connection to a remote server. When you create a tunnel, your SSH client listens on a port on your local laptop. Any data sent to that local port is encrypted, sent over the SSH connection to the remote VPS, and then forwarded to a specific destination (like your OpenClaw Gateway). ## Why it matters for OpenClaw The OpenClaw Gateway listens on `localhost:18789` by default. This means it can only be accessed from *inside* the VPS. You cannot type your VPS IP address into your browser to see the dashboard because your firewall blocks it (and you shouldn't allow it). An SSH tunnel bridges this gap perfectly. By running a single command on your laptop: ```bash ssh -L 18789:localhost:18789 clawuser@your_server_ip ``` You are telling SSH: "Take port 18789 on my laptop, and securely connect it to localhost:18789 on the VPS." You can then open your web browser and go to `http://localhost:18789`. You will see the OpenClaw dashboard, but the traffic is safely traveling through the encrypted SSH tunnel. ## Common mistake **Closing the terminal that is running the tunnel.** The SSH tunnel only exists as long as that specific SSH connection is open. If you close the terminal window where you ran the `ssh -L` command, the tunnel collapses, and your dashboard will immediately show "Site cannot be reached." **Fix:** Keep the terminal window open while you are using the dashboard. You can minimize it, but do not close it. ## Related guides - [Why Port 18789 Must Stay Private](/guides/openclaw-gateway-port-18789) - [Install OpenClaw on Ubuntu VPS](/guides/install-openclaw-ubuntu-vps) - [What is SSH?](/glossary/ssh) - [Dashboard Not Opening](/troubleshooting/dashboard-not-opening) --- ### ssh.mdx URL: https://www.clawready.in/glossary/ssh/ ## What is SSH? **SSH (Secure Shell)** is an encrypted network protocol that lets you connect to a remote server and run commands securely. When you type `ssh clawuser@your_server_ip` in your terminal, an encrypted tunnel is created between your local machine and the VPS. Everything you type and everything the server sends back is encrypted — no one in between can read it. SSH has two main uses for OpenClaw: 1. **Remote server access** — connecting to your VPS to install, configure, and manage OpenClaw. 2. **SSH tunneling** — securely forwarding a remote port (like 18789) to your local machine so you can access the dashboard without exposing it to the internet. ## Key concepts ### SSH keys vs passwords There are two ways to authenticate over SSH: - **Password authentication** — you type a password each time. This is vulnerable to brute-force attacks where automated scripts try thousands of passwords per minute. - **SSH key authentication** — you generate a key pair (public + private). The public key goes on the server, the private key stays on your machine. No password is transmitted over the network. ### SSH tunneling SSH tunneling (also called port forwarding) lets you securely access a service running on your VPS from your local browser: ```bash ssh -L 18789:localhost:18789 clawuser@your_server_ip ``` This command forwards port 18789 on your local machine to port 18789 on the VPS. You can then open `http://localhost:18789` in your browser to access the OpenClaw dashboard — without exposing the port to the public internet. ## Why it matters for OpenClaw Without SSH, you cannot manage your VPS or access the OpenClaw dashboard safely. SSH tunneling is the **recommended method** for beginners to access the dashboard, because it requires no firewall changes and no reverse proxy setup. ## Common mistake **Keeping password authentication enabled.** After setting up SSH keys, many users forget to disable password login. This leaves the server vulnerable to brute-force attacks even though keys are configured. **Fix:** Edit `/etc/ssh/sshd_config` and set: ``` PasswordAuthentication no ``` Then restart SSH: ```bash sudo systemctl restart sshd ``` ## Related guides - [Fresh Ubuntu VPS Setup](/guides/fresh-ubuntu-vps-setup) — includes SSH key setup - [OpenClaw Gateway Port 18789](/guides/openclaw-gateway-port-18789) — SSH tunnel instructions - [OpenClaw VPS Security Checklist](/guides/openclaw-vps-security-checklist) — SSH hardening steps --- ### tailscale.mdx URL: https://www.clawready.in/glossary/tailscale/ ## What is Tailscale? **Tailscale** is a mesh VPN service that makes it incredibly easy to connect your devices together securely. It uses the WireGuard protocol under the hood. When you install Tailscale on your laptop and your VPS, they join your private "Tailnet." Tailscale assigns each device a special private IP address (usually starting with `100.`). Devices on the Tailnet can communicate with each other as if they were on the same physical local network, even if they are on different continents. ## Why it matters for OpenClaw Accessing the OpenClaw dashboard safely requires keeping port `18789` hidden from the public internet. While an [SSH Tunnel](/glossary/ssh-tunnel) works great, you have to run a terminal command every time you want to open the dashboard. Tailscale offers a more seamless experience. If you configure OpenClaw to listen on its Tailscale IP (or use Tailscale's magic routing), you can simply type `http://your-vps-name:18789` into your laptop's browser. The traffic travels securely over the encrypted Tailnet. To the outside world, the port remains completely invisible. ## Common mistake **Binding to `0.0.0.0` thinking Tailscale will protect you.** Some users install Tailscale, but then configure their Gateway with `OPENCLAW_HOST=0.0.0.0` and run `sudo ufw allow 18789`. This defeats the entire purpose of Tailscale. `0.0.0.0` listens on *all* interfaces, including the public internet one. **Fix:** If you are using Tailscale, configure your OpenClaw Gateway to bind *only* to the Tailscale IP (e.g., `OPENCLAW_HOST=100.x.x.x`), or keep it on `127.0.0.1` and use Tailscale's feature called "Tailscale Serve." Never open port 18789 in your UFW firewall. ## Related guides - [OpenClaw Tailscale Setup](/guides/openclaw-tailscale-setup) - [OpenClaw VPS Security Checklist](/guides/openclaw-vps-security-checklist) - [What is an SSH Tunnel?](/glossary/ssh-tunnel) --- ### vps.mdx URL: https://www.clawready.in/glossary/vps/ ## What is a VPS? A **Virtual Private Server (VPS)** is a remote computer hosted in a data centre. You rent it from a provider like DigitalOcean, Hetzner, Hostinger, or AWS Lightsail. You connect to it over the internet using SSH (Secure Shell) and run commands as if you were sitting in front of it. Unlike shared hosting, a VPS gives you: - **Full control** — you can install any software, configure firewalls, and manage users. - **Dedicated resources** — your CPU, RAM, and storage are not shared with other customers. - **A public IP address** — your server is reachable from the internet (which is both useful and dangerous). - **Always-on availability** — it does not shut down when you close your laptop. ## Why it matters for OpenClaw OpenClaw Gateway is a long-running process. It needs to stay online to receive messages from Telegram, WhatsApp, or other channels. If the process stops, your bot stops responding. A VPS solves this by providing a stable, always-on environment. Most Indian builders use a VPS priced between ₹300–₹1500/month. ## Common mistake **Running OpenClaw as root.** When you first log into a VPS, you are usually the `root` user with full system access. If you install and run OpenClaw as root, any security vulnerability in OpenClaw, its dependencies, or your AI model provider could give an attacker complete control over your server. **Fix:** Create a dedicated non-root user before installing anything: ```bash adduser clawuser usermod -aG sudo clawuser ``` Then log in as `clawuser` for all OpenClaw operations. ## Related guides - [Fresh Ubuntu VPS Setup](/guides/fresh-ubuntu-vps-setup) - [Install OpenClaw on Ubuntu VPS](/guides/install-openclaw-ubuntu-vps) - [OpenClaw VPS Security Checklist](/guides/openclaw-vps-security-checklist) - [OpenClaw on Hostinger VPS](/guides/openclaw-hostinger-vps) --- ### webhook.mdx URL: https://www.clawready.in/glossary/webhook/ ## What is a Webhook? A **webhook** is an HTTP-based callback function. It allows systems to communicate instantly. Think of it like getting food delivered: - **Polling:** You call the restaurant every 5 minutes asking, "Is my food ready yet?" - **Webhook:** You give the restaurant your phone number, and they text you the exact moment it is ready. ## Why it matters for OpenClaw When a user sends a message to your OpenClaw bot on Telegram or WhatsApp, that message hits the provider's servers first. The provider needs a way to send it to your Gateway. There are two ways to do this: 1. **Polling:** OpenClaw constantly asks Telegram, "Any new messages?" This works great locally or behind firewalls, but can be slightly slower. 2. **Webhooks:** Telegram instantly POSTs the message to a specific URL on your server. This is faster and uses less bandwidth. To use webhooks for production, you must provide Telegram with a public, HTTPS-secured URL (e.g., `https://api.my-agent.com/webhook/telegram`). This requires setting up a [Reverse Proxy](/glossary/reverse-proxy) with an SSL certificate. ## Common mistake **Configuring a webhook without HTTPS.** Telegram enforces strict security. If you tell Telegram to send webhooks to an `http://` address, or an IP address, or an address with an invalid SSL certificate, Telegram will simply drop the messages. Your OpenClaw Gateway will never receive them, and your bot will not reply. **Fix:** If you do not know how to configure Nginx and Let's Encrypt for HTTPS, do not use webhooks. Use standard polling instead, which works perfectly behind an [SSH Tunnel](/glossary/ssh-tunnel) or NAT without exposing any ports. ## Related guides - [OpenClaw Telegram Channel Setup](/guides/openclaw-telegram-setup) - [Telegram Bot Not Replying](/troubleshooting/telegram-bot-not-replying) - [What is a Reverse Proxy?](/glossary/reverse-proxy) ---