Jordan Ramos
e08951de21
- Add Docker Compose configs with security hardening (cap_drop ALL, non-root, read-only FS) - Add Prometheus node_exporter scrape target for 192.168.2.120:9100 - Update services/README.md, INDEX.md, and CLAUDE_STATUS.md with VM 120 - Image pinned to v2026.2.1 (patches CVE-2026-25253) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
242 lines
7.3 KiB
Markdown
242 lines
7.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
curl -sf http://192.168.1.81:11434/api/tags | head -5
|
|
```
|
|
|
|
After editing, restart the container:
|
|
|
|
```bash
|
|
cd /opt/openclaw && sudo docker compose down && sudo docker compose up -d
|
|
```
|
|
|
|
Verify the provider is loaded:
|
|
|
|
```bash
|
|
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](https://t.me/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:
|
|
|
|
```bash
|
|
cd /opt/openclaw && sudo docker compose down && sudo docker compose up -d
|
|
```
|
|
|
|
Confirm platform connections in the logs:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo nano /opt/prometheus/prometheus.yml
|
|
```
|
|
|
|
3. Add the following scrape job under `scrape_configs`:
|
|
|
|
```yaml
|
|
- job_name: 'openclaw-node'
|
|
static_configs:
|
|
- targets: ['192.168.2.120:9100']
|
|
labels:
|
|
instance: 'openclaw'
|
|
vm_id: '120'
|
|
```
|
|
|
|
4. Restart the Prometheus container:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|