OpenClaw: Self-Hosted AI Agent Platform Configuration and Operations

Overview

OpenClaw is a self-hosted AI agent platform that connects to messaging channels and runs autonomously 24/7. The agent uses Claude (or other LLMs) as its brain.

Key concepts:

• Gateway: Node.js process (port 18789) that routes messages, runs cron, manages tools
• Agent: LLM-powered brain that reads/writes memory files and calls tools
• Channels: Telegram, WhatsApp, Discord, Slack, Signal, iMessage/BlueBubbles
• Skills: Markdown files in ~/.openclaw/workspace/skills/
• Memory: MEMORY.md, NOTES.md, HEARTBEAT.md in ~/.openclaw/workspace/
• State dir: ~/.openclaw/ (or $OPENCLAW_STATE_DIR)

Config File

~/.openclaw/openclaw.json — JSON5 format (comments allowed).

{
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1"  // never expose publicly; use Tailscale
  },
  "agents": [
    {
      "id": "primary",
      "model": "claude-opus-4-6",
      "memoryFile": "~/.openclaw/workspace/MEMORY.md",
      "notesFile": "~/.openclaw/workspace/NOTES.md"
    }
  ],
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "$TELEGRAM_BOT_TOKEN",
      "allowedUsers": ["@yourusername"]
    },
    "discord": {
      "enabled": true,
      "token": "$DISCORD_BOT_TOKEN",
      "allowedChannels": ["agent-commands"]
    }
  },
  "skills": {
    "directories": ["~/.openclaw/workspace/skills/"]
  }
}

Essential Commands

# Status and health
openclaw status
openclaw health
openclaw gateway status
openclaw doctor
openclaw logs --follow

# Gateway control
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway install        # install as system service

# Channels
openclaw channels status --probe
openclaw channels login --channel whatsapp
openclaw pairing list telegram

# Skills
openclaw skills list
openclaw skills reload

VPS Installation

# Prerequisites
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install OpenClaw
npm install -g @openclaw/cli

# Initialize
openclaw init
openclaw setup

# Verify
openclaw doctor

Security: Tailscale + UFW Lockdown

Never expose the OpenClaw gateway publicly. Use Tailscale as the control plane:

# Install Tailscale
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --authkey=tskey-...

# Lock down with UFW
sudo ufw default deny incoming
sudo ufw allow ssh
sudo ufw allow in on tailscale0      # allow Tailscale traffic
sudo ufw enable

# Verify gateway is only reachable via Tailscale
curl http://100.x.x.x:18789/health   # Tailscale IP

Memory Files

The agent reads and writes these files to maintain context across sessions:

<!-- MEMORY.md — Long-term knowledge -->
# Agent Memory

## Projects
- Project X: Next.js app at /home/user/projects/x

## Preferences
- Always use TypeScript
- Deploy to Vercel

<!-- NOTES.md — Working notes and scratchpad -->
# Current Notes
...

<!-- HEARTBEAT.md — Cron status and last actions -->
# Heartbeat Log
Last ping: 2026-05-12T10:00:00Z
Status: active

Skills

Skills are markdown files that extend agent capabilities:

<!-- ~/.openclaw/workspace/skills/web-search.md -->
---
name: web-search
description: Search the web and return summarized results
---

# Web Search

When the user asks to search the web, use Brave Search API:

## Instructions
Call: GET https://api.search.brave.com/res/v1/web/search?q={query}
Header: X-Subscription-Token: $BRAVE_API_KEY
Return top 3 results with title, url, and snippet.

Cron Jobs

{
  "cron": [
    {
      "schedule": "0 9 * * 1-5",      // 9am weekdays
      "message": "Morning briefing: summarize pending tasks from NOTES.md",
      "channel": "telegram"
    },
    {
      "schedule": "*/30 * * * *",     // every 30 minutes
      "message": "Heartbeat check: update HEARTBEAT.md with status",
      "channel": "internal"
    }
  ]
}

Triage Checklist for Broken Gateway

Before changing anything, collect:

df -h /                              # disk usage
ps aux | grep openclaw               # active processes
netstat -tlnp | grep 18789           # gateway port
tailscale status                     # Tailscale connectivity
sudo ufw status                      # firewall rules
openclaw --version                   # installed version
openclaw doctor                      # health report

If disk is over 90%, clean logs/cache before installing or upgrading. Never delete repos, data, chat-backups, or .openclaw memory folders without explicit confirmation.

Model Routing

{
  "agents": [
    {
      "id": "primary",
      "model": "claude-opus-4-6",    // heavy reasoning tasks
      "fallback": "claude-haiku-4-5" // heartbeat, simple checks
    }
  ]
}

Use Gemini CLI for lightweight heartbeat work to avoid Anthropic usage on routine checks.

Common Issues

| Symptom | Cause | Fix | |---------|-------|-----| | Gateway not responding | Port 18789 blocked | Check UFW, ensure Tailscale IP allowed | | Telegram not pairing | Bot token expired | Regenerate via BotFather, update config | | Skills not loading | Wrong directory path | Verify skills.directories in config | | High token usage | Too many cron tasks | Add Gemini fallback for routine checks | | Memory not persisting | File permissions | chmod 644 ~/.openclaw/workspace/*.md |