# OpenClaw Deployment
OpenClaw is a personal AI assistant that runs on your VPS and connects to messaging platforms (WhatsApp, Telegram, Slack, Discord, etc.).
## Architecture
```
Your Phone (WhatsApp/Telegram)
↓ (outbound HTTPS to messaging APIs)
Your VPS (OpenClaw Gateway)
↓ (binds to Tailscale IP)
Your Laptop (Web UI access via Tailscale)
```
## Prerequisites
1. **Bootstrap layer** must be run first (users, SSH, firewall)
2. **Infrastructure layer** must be run with Tailscale enabled
- Tailscale is installed via `infrastructure.yml` playbook
- Provides secure VPN mesh network for accessing OpenClaw gateway
- OpenClaw gateway binds to Tailscale IP (not public internet)
3. **Environment variables** must be set (see Configuration below)
## Configuration
### Required Config Values
Set in `config.toml` (see [Secrets Management](configuration/secrets.md)):
```bash
auberge config set openclaw_gateway_token your-token
auberge config set openclaw_claude_ai_session_key your-session-key
```
Optional values:
```bash
auberge config set openclaw_claude_web_session_key your-web-session-key
auberge config set openclaw_claude_web_cookie your-cookie
```
### Generate Gateway Token
```bash
openssl rand -hex 32
```
### Get Claude AI Session Key
1. Log in to https://claude.ai
2. Open browser DevTools (F12)
3. Go to Application → Cookies
4. Copy `sessionKey` value
## Deployment
### Deploy OpenClaw Only
```bash
auberge ansible run --tags openclaw
```
### Deploy with Other Layers
```bash
# Deploy infrastructure and openclaw together
auberge ansible run --tags infrastructure,openclaw
# Or bootstrap + infrastructure + openclaw
auberge ansible run --tags bootstrap,infrastructure,openclaw
# Or full deployment (includes all apps)
auberge ansible run
```
### Check Mode (Dry Run)
```bash
auberge ansible run --tags openclaw --check
```
## Post-Deployment Setup
### 1. SSH to VPS
```bash
ssh user@your-vps
```
### 2. Run Onboarding Wizard
```bash
openclaw onboard
```
The wizard will guide you through:
- Connecting messaging channels (WhatsApp, Telegram, etc.)
- Configuring AI model preferences
- Setting up skills and workspace
### 3. Connect Messaging Platforms
**WhatsApp:**
- Wizard will show QR code
- Scan with WhatsApp on your phone
- OpenClaw connects via Baileys library
**Telegram:**
1. Create bot via @BotFather
2. Copy bot token
3. Provide to wizard
**Slack:**
1. Create bot in Slack workspace
2. Copy bot token
3. Provide to wizard
**Discord:**
1. Create bot in Discord Developer Portal
2. Copy bot token
3. Provide to wizard
### 4. Access Web UI
**Install Tailscale on laptop:**
```bash
# macOS/Linux
https://tailscale.com/download
# Log in with same account as VPS
tailscale login
```
**Access gateway:**
```bash
# Find VPS Tailscale IP
ssh user@your-vps
tailscale ip -4
# Browse to (from laptop with Tailscale)
http://100.64.0.X:18789
```
## Service Management
### Check Service Status
```bash
systemctl --user status openclaw-gateway
```
### View Logs
```bash
journalctl --user -u openclaw-gateway -f
```
### Restart Service
```bash
systemctl --user restart openclaw-gateway
```
### Stop Service
```bash
systemctl --user stop openclaw-gateway
```
### Disable Service
```bash
systemctl --user disable openclaw-gateway
```
## Daily Usage
### Messaging Platforms
Once connected, just message openclaw via your preferred platform:
- **WhatsApp**: Send message to paired phone number
- **Telegram**: Message your bot
- **Slack**: @mention the bot in channels
- **Discord**: @mention the bot in channels
The AI responds in the same channel automatically.
### CLI Commands (via SSH)
```bash
ssh user@your-vps
openclaw message send --to +1234567890 --message "Hello"
openclaw agent --message "Ship checklist" --thinking high
openclaw doctor
```
## Security
### Network Exposure
- **Public Internet**: Only SSH (22) + Tailscale (41641/udp)
- **OpenClaw Ports**: NOT exposed publicly
- **Gateway Binding**: Tailscale IP only (100.64.0.X)
- **Access Method**: Via Tailscale VPN
### Firewall Rules (UFW)
```bash
22/tcp ALLOW # SSH
41641/udp ALLOW # Tailscale
18789/tcp DENY # OpenClaw gateway (Tailscale-only)
18790/tcp DENY # Reserved for future OpenClaw bridge (currently unused)
```
### Secret Management
- Sensitive values stored in `config.toml` (not version controlled)
- Never commit `config.toml`
- Rotate tokens regularly
- Use strong gateway token (generate with `openssl rand -hex 32`)
- Secrets are deployed to `{{ openclaw_config_dir }}/env` with mode `0600` (owner-only read/write)
- The systemd service loads secrets via `EnvironmentFile=` — they never appear in the service unit file
## Troubleshooting
### Service Won't Start
```bash
journalctl --user -u openclaw-gateway -n 50
```
Check for:
- Missing environment variables
- Node.js version < 22
- Port conflicts
### Can't Access Web UI
1. Verify Tailscale running:
```bash
tailscale status
```
2. Check gateway binding:
```bash
ss -tlnp | grep 18789
```
3. Verify Tailscale IP:
```bash
tailscale ip -4
```
### Messaging Platform Not Responding
```bash
openclaw doctor
journalctl --user -u openclaw-gateway -f
```
Check for:
- Session expired (re-run onboarding)
- Network connectivity
- API rate limits
## Updates
### Update OpenClaw
```bash
ssh user@your-vps
npm update -g openclaw
systemctl --user restart openclaw-gateway
```
### Update via Ansible
```bash
auberge ansible run --tags openclaw
```
## Removal
### Stop and Disable Service
```bash
ssh user@your-vps
systemctl --user stop openclaw-gateway
systemctl --user disable openclaw-gateway
```
### Uninstall OpenClaw
```bash
npm uninstall -g openclaw
rm -rf ~/.openclaw
rm ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload
```
## References
- [OpenClaw Docs](https://docs.openclaw.ai)
- [Getting Started](https://docs.openclaw.ai/start/getting-started)
- [Tailscale Setup](https://tailscale.com/kb/1017/install)
- [WhatsApp Integration](https://docs.openclaw.ai/channels/whatsapp)
- [Telegram Integration](https://docs.openclaw.ai/channels/telegram)