homelab/services/openclaw/GETTING-STARTED.md

OpenClaw - Getting Started

This guide picks up after the base deployment on VM 120 is complete. It walks through configuring LLM providers, messaging platforms, reverse proxy, remote access, and monitoring.

Prerequisites

Before proceeding, confirm the following are in place:

• VM 120 running at 192.168.2.120 (cloned from template 107)
• Docker and Docker Compose installed
• OpenClaw container deployed and healthy (docker ps --filter name=openclaw shows healthy)
• .env file created from .env.example with GATEWAY_TOKEN populated
• Data directories exist at /opt/openclaw/{data,sessions,logs} owned by 1001:1001

If any of the above are missing, refer to the Deployment section in /home/jramos/homelab/services/openclaw/README.md.

---

Step 1: Configure an LLM Provider

The bot will not respond to messages until at least one LLM provider is configured.

SSH to VM 120 and edit the environment file:

ssh jramos@192.168.2.120
sudo nano /opt/openclaw/.env

Set one or more of the following:

Variable	Notes
ANTHROPIC_API_KEY	Anthropic API key from https://console.anthropic.com/
OPENAI_API_KEY	OpenAI API key from https://platform.openai.com/api-keys
OLLAMA_BASE_URL	Pre-configured to http://192.168.1.81:11434 (local Ollama instance)

If you are using the local Ollama instance, no changes are needed -- the default .env.example already points to http://192.168.1.81:11434. Verify Ollama is reachable from VM 120:

curl -sf http://192.168.1.81:11434/api/tags | head -5

After editing, restart the container:

cd /opt/openclaw && sudo docker compose down && sudo docker compose up -d

Verify the provider is loaded:

sudo docker exec openclaw env | grep -E 'ANTHROPIC|OPENAI|OLLAMA'

---

Step 2: Configure Messaging Platforms (Optional)

Add platform tokens to /opt/openclaw/.env as needed. Each platform requires its own bot/app registration.

Discord

1. Go to https://discord.com/developers/applications and create a new application.
2. Navigate to Bot > Add Bot. Copy the bot token.
3. Under Privileged Gateway Intents, enable Message Content Intent.
4. Set DISCORD_TOKEN=<your-token> in .env.
5. Invite the bot to your server using the OAuth2 URL Generator (scopes: bot, permissions: Send Messages, Read Message History).

Telegram

1. Message @BotFather on Telegram and run /newbot.
2. Follow the prompts to name your bot. Copy the token provided.
3. Set TELEGRAM_TOKEN=<your-token> in .env.

Slack

1. Go to https://api.slack.com/apps and click Create New App > From scratch.
2. Under OAuth & Permissions, add bot scopes: chat:write, channels:history, im:history.
3. Install the app to your workspace and copy the Bot User OAuth Token.
4. Set SLACK_TOKEN=xoxb-<your-token> in .env.

WhatsApp

1. Set up a WhatsApp Business API account via https://developers.facebook.com/.
2. Configure a webhook URL pointing to https://openclaw.apophisnetworking.net (requires Step 3 first).
3. Set WHATSAPP_TOKEN=<your-token> in .env.

After adding any tokens, restart the container:

cd /opt/openclaw && sudo docker compose down && sudo docker compose up -d

Confirm platform connections in the logs:

sudo docker logs openclaw 2>&1 | grep -iE 'connect|discord|telegram|slack|whatsapp'

---

Step 3: Set Up Reverse Proxy (NPM)

OpenClaw binds all ports to 127.0.0.1, so a reverse proxy is required for external access.

1. Access Nginx Proxy Manager at http://192.168.2.101:81.
2. Click Proxy Hosts > Add Proxy Host.
3. Configure:

Field	Value
Domain Names	openclaw.apophisnetworking.net
Scheme	http
Forward Hostname/IP	192.168.2.120
Forward Port	18789
Websockets Support	Enabled (required -- gateway uses WebSockets)

4. Under the SSL tab:

   • Select Request a new SSL Certificate via Let's Encrypt.
   • Enable Force SSL and HTTP/2 Support.

5. (Optional) To add TinyAuth protection, go to the Advanced tab and paste the auth_request configuration block documented in /home/jramos/homelab/services/tinyauth/README.md (Nginx Proxy Manager Configuration section), adjusting the proxy_pass target to your TinyAuth instance.

6. Save and verify:

curl -sf https://openclaw.apophisnetworking.net

---

Step 4: Add Twingate Resource

To enable zero-trust remote access to VM 120:

1. Log into the Twingate Admin Console.
2. Navigate to Resources > Add Resource.
3. Add a resource with address 192.168.2.120.
4. Add the following ports:
   • 18789 (Gateway WS+UI)
   • 18790 (Bridge)
   • 1455 (OAuth)
5. Assign the resource to the appropriate user groups.

---

Step 5: Deploy Prometheus Config to VM 101

Add the OpenClaw host to Prometheus so node-level metrics appear in Grafana.

1. Access VM 101 (monitoring-docker) console via the Proxmox web UI at https://192.168.2.100:8006.
2. Edit the Prometheus configuration:

sudo nano /opt/prometheus/prometheus.yml

3. Add the following scrape job under scrape_configs:

  - job_name: 'openclaw-node'
    static_configs:
      - targets: ['192.168.2.120:9100']
        labels:
          instance: 'openclaw'
          vm_id: '120'

4. Restart the Prometheus container:

cd /opt/prometheus && sudo docker compose restart prometheus

5. Verify the target is up at http://192.168.2.114:9090/targets -- look for openclaw-node with state UP.

---

Step 6: Verify Everything Works

Run through this checklist from VM 120 (unless noted otherwise):

# Container healthy
sudo docker ps --filter name=openclaw
# STATUS column should show "healthy"

# Gateway responding
curl -sf http://localhost:18789/health
# Should return JSON with 200 status

# Node exporter serving metrics
curl -sf http://localhost:9100/metrics | head -5
# Should return Prometheus metric lines

# Version check
sudo docker logs openclaw 2>&1 | head -10
# Confirm version >= 2026.2.1

# NPM proxy (from any machine with DNS access, after Step 3)
curl -sf https://openclaw.apophisnetworking.net
# Should return the web UI or a redirect to login

# Prometheus target (after Step 5)
# Open http://192.168.2.114:9090/targets in a browser
# openclaw-node should show state UP

---

Common Operations

# View logs (live)
sudo docker logs -f openclaw

# Restart
cd /opt/openclaw && sudo docker compose restart

# Update to a new version
cd /opt/openclaw && sudo docker compose pull && sudo docker compose up -d

# Backup application data
sudo -u openclaw /opt/openclaw/backup.sh

---

Security Reminders

• Never commit .env to git. It is excluded via .gitignore, but verify before pushing.
• Keep version >= 2026.2.1. CVE-2026-25253 (1-click RCE, CVSS 8.8) is patched in this release. Do not downgrade.
• Only install vetted skills. Use the skill-vetter tool to audit any skill before installation. Avoid skills that require shell access, computer-use, or deployment capabilities.
• Keep DM_POLICY=pairing. This prevents unauthorized users from interacting with the bot via direct messages.
• File permissions. The .env file must be chmod 600 (owner-only read/write).

---

Maintained by: Homelab Infrastructure Team Last Updated: 2026-02-03