# Troubleshooting

Common issues when setting up OpenClaw on a VPS, and how to fix them.

---

### `openclaw: command not found` after switching users

The install added `openclaw` to a path your shell isn't reading. Fix the PATH:

```bash
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
openclaw --version
```

---

### The bot doesn't reply in Telegram

Check, in order:

1. **Is the service running?**
   ```bash
   openclaw status
   openclaw gateway status
   ```
2. **Was the pairing approved?**
   ```bash
   openclaw pairing list telegram
   openclaw pairing approve telegram --notify
   ```
3. **Is the bot token correct?** Re-check the token from @BotFather (no extra spaces). Re-run `openclaw onboard` if needed.
4. **Watch the live logs** while you send a message:
   ```bash
   openclaw logs --follow
   ```

---

### It stops working after I close my SSH session

You didn't enable "linger", so the user service stops on logout. Turn it on:

```bash
sudo loginctl enable-linger $USER
```

Then restart:

```bash
systemctl --user restart openclaw-gateway.service
```

---

### The agent is slow, crashes, or gets "killed"

Usually **out of memory** on a 1 GB droplet. Add swap:

```bash
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h   # confirm swap is active
```

If it's still tight, resize the droplet to 2 GB RAM in the DigitalOcean panel.

---

### `node: command not found` or wrong Node version

OpenClaw needs **Node 22+**. Reinstall:

```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs
node --version
```

---

### LLM errors (401 / invalid key / quota)

- **401 / invalid key:** the API key is wrong or revoked. Get a fresh one from [Anthropic](https://console.anthropic.com) or [OpenAI](https://platform.openai.com) and re-run onboarding.
- **Quota / billing:** add credit/billing to your LLM provider account. New keys sometimes need a payment method before they work.

---

### I can't open the control UI

Don't expose port `18789` to the internet. Use an SSH tunnel from **your own computer**:

```bash
ssh -L 18789:localhost:18789 root@YOUR_SERVER_IP
# then visit http://localhost:18789
```

---

### Locked out / can't SSH in

- Double-check the **IP address** and that you're using the right **SSH key**.
- In the DigitalOcean panel, use the **web Console** to log in directly and check `sudo ufw status` — make sure `OpenSSH` is allowed.

---

Still stuck? The official docs cover edge cases: https://docs.openclaw.ai — or reach out and we'll set it up for you.