{"slug":"openclaw-agent-platform","title":"OpenClaw: Self-Hosted AI Agent Platform Configuration and Operations","tags":["openclaw","agents","self-hosted","telegram","discord","whatsapp","vps"],"agent_summary":"OpenClaw self-hosted AI agent platform — gateway architecture, config file structure, channel setup (Telegram/Discord/WhatsApp), skills, memory files, cron jobs, VPS installation, Tailscale lockdown, and troubleshooting.","trigger_phrases":["OpenClaw","openclaw config","self-hosted agent","OpenClaw VPS","openclaw gateway","OpenClaw Telegram","OpenClaw Discord","openclaw skills"],"runnable":false,"markdown":"\n## Overview\n\nOpenClaw 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.\n\n**Key concepts:**\n- **Gateway**: Node.js process (port 18789) that routes messages, runs cron, manages tools\n- **Agent**: LLM-powered brain that reads/writes memory files and calls tools\n- **Channels**: Telegram, WhatsApp, Discord, Slack, Signal, iMessage/BlueBubbles\n- **Skills**: Markdown files in `~/.openclaw/workspace/skills/`\n- **Memory**: `MEMORY.md`, `NOTES.md`, `HEARTBEAT.md` in `~/.openclaw/workspace/`\n- **State dir**: `~/.openclaw/` (or `$OPENCLAW_STATE_DIR`)\n\n## Config File\n\n`~/.openclaw/openclaw.json` — JSON5 format (comments allowed).\n\n```json5\n{\n  \"gateway\": {\n    \"port\": 18789,\n    \"host\": \"127.0.0.1\"  // never expose publicly; use Tailscale\n  },\n  \"agents\": [\n    {\n      \"id\": \"primary\",\n      \"model\": \"claude-opus-4-6\",\n      \"memoryFile\": \"~/.openclaw/workspace/MEMORY.md\",\n      \"notesFile\": \"~/.openclaw/workspace/NOTES.md\"\n    }\n  ],\n  \"channels\": {\n    \"telegram\": {\n      \"enabled\": true,\n      \"token\": \"$TELEGRAM_BOT_TOKEN\",\n      \"allowedUsers\": [\"@yourusername\"]\n    },\n    \"discord\": {\n      \"enabled\": true,\n      \"token\": \"$DISCORD_BOT_TOKEN\",\n      \"allowedChannels\": [\"agent-commands\"]\n    }\n  },\n  \"skills\": {\n    \"directories\": [\"~/.openclaw/workspace/skills/\"]\n  }\n}\n```\n\n## Essential Commands\n\n```bash\n# Status and health\nopenclaw status\nopenclaw health\nopenclaw gateway status\nopenclaw doctor\nopenclaw logs --follow\n\n# Gateway control\nopenclaw gateway start\nopenclaw gateway stop\nopenclaw gateway restart\nopenclaw gateway install        # install as system service\n\n# Channels\nopenclaw channels status --probe\nopenclaw channels login --channel whatsapp\nopenclaw pairing list telegram\n\n# Skills\nopenclaw skills list\nopenclaw skills reload\n```\n\n## VPS Installation\n\n```bash\n# Prerequisites\ncurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -\nsudo apt-get install -y nodejs\n\n# Install OpenClaw\nnpm install -g @openclaw/cli\n\n# Initialize\nopenclaw init\nopenclaw setup\n\n# Verify\nopenclaw doctor\n```\n\n## Security: Tailscale + UFW Lockdown\n\nNever expose the OpenClaw gateway publicly. Use Tailscale as the control plane:\n\n```bash\n# Install Tailscale\ncurl -fsSL https://tailscale.com/install.sh | sh\nsudo tailscale up --authkey=tskey-...\n\n# Lock down with UFW\nsudo ufw default deny incoming\nsudo ufw allow ssh\nsudo ufw allow in on tailscale0      # allow Tailscale traffic\nsudo ufw enable\n\n# Verify gateway is only reachable via Tailscale\ncurl http://100.x.x.x:18789/health   # Tailscale IP\n```\n\n## Memory Files\n\nThe agent reads and writes these files to maintain context across sessions:\n\n```markdown\n<!-- MEMORY.md — Long-term knowledge -->\n# Agent Memory\n\n## Projects\n- Project X: Next.js app at /home/user/projects/x\n\n## Preferences\n- Always use TypeScript\n- Deploy to Vercel\n```\n\n```markdown\n<!-- NOTES.md — Working notes and scratchpad -->\n# Current Notes\n...\n```\n\n```markdown\n<!-- HEARTBEAT.md — Cron status and last actions -->\n# Heartbeat Log\nLast ping: 2026-05-12T10:00:00Z\nStatus: active\n```\n\n## Skills\n\nSkills are markdown files that extend agent capabilities:\n\n```markdown\n<!-- ~/.openclaw/workspace/skills/web-search.md -->\n---\nname: web-search\ndescription: Search the web and return summarized results\n---\n\n# Web Search\n\nWhen the user asks to search the web, use Brave Search API:\n\n## Instructions\nCall: GET https://api.search.brave.com/res/v1/web/search?q={query}\nHeader: X-Subscription-Token: $BRAVE_API_KEY\nReturn top 3 results with title, url, and snippet.\n```\n\n## Cron Jobs\n\n```json5\n{\n  \"cron\": [\n    {\n      \"schedule\": \"0 9 * * 1-5\",      // 9am weekdays\n      \"message\": \"Morning briefing: summarize pending tasks from NOTES.md\",\n      \"channel\": \"telegram\"\n    },\n    {\n      \"schedule\": \"*/30 * * * *\",     // every 30 minutes\n      \"message\": \"Heartbeat check: update HEARTBEAT.md with status\",\n      \"channel\": \"internal\"\n    }\n  ]\n}\n```\n\n## Triage Checklist for Broken Gateway\n\nBefore changing anything, collect:\n\n```bash\ndf -h /                              # disk usage\nps aux | grep openclaw               # active processes\nnetstat -tlnp | grep 18789           # gateway port\ntailscale status                     # Tailscale connectivity\nsudo ufw status                      # firewall rules\nopenclaw --version                   # installed version\nopenclaw doctor                      # health report\n```\n\nIf disk is over 90%, clean logs/cache before installing or upgrading. Never delete repos, data, chat-backups, or .openclaw memory folders without explicit confirmation.\n\n## Model Routing\n\n```json5\n{\n  \"agents\": [\n    {\n      \"id\": \"primary\",\n      \"model\": \"claude-opus-4-6\",    // heavy reasoning tasks\n      \"fallback\": \"claude-haiku-4-5\" // heartbeat, simple checks\n    }\n  ]\n}\n```\n\nUse Gemini CLI for lightweight heartbeat work to avoid Anthropic usage on routine checks.\n\n## Common Issues\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Gateway not responding | Port 18789 blocked | Check UFW, ensure Tailscale IP allowed |\n| Telegram not pairing | Bot token expired | Regenerate via BotFather, update config |\n| Skills not loading | Wrong directory path | Verify `skills.directories` in config |\n| High token usage | Too many cron tasks | Add Gemini fallback for routine checks |\n| Memory not persisting | File permissions | `chmod 644 ~/.openclaw/workspace/*.md` |\n","html":"<h2>Overview</h2>\n<p>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.</p>\n<p><strong>Key concepts:</strong></p>\n<ul>\n<li><strong>Gateway</strong>: Node.js process (port 18789) that routes messages, runs cron, manages tools</li>\n<li><strong>Agent</strong>: LLM-powered brain that reads/writes memory files and calls tools</li>\n<li><strong>Channels</strong>: Telegram, WhatsApp, Discord, Slack, Signal, iMessage/BlueBubbles</li>\n<li><strong>Skills</strong>: Markdown files in <code>~/.openclaw/workspace/skills/</code></li>\n<li><strong>Memory</strong>: <code>MEMORY.md</code>, <code>NOTES.md</code>, <code>HEARTBEAT.md</code> in <code>~/.openclaw/workspace/</code></li>\n<li><strong>State dir</strong>: <code>~/.openclaw/</code> (or <code>$OPENCLAW_STATE_DIR</code>)</li>\n</ul>\n<h2>Config File</h2>\n<p><code>~/.openclaw/openclaw.json</code> — JSON5 format (comments allowed).</p>\n<pre><code class=\"language-json5\">{\n  \"gateway\": {\n    \"port\": 18789,\n    \"host\": \"127.0.0.1\"  // never expose publicly; use Tailscale\n  },\n  \"agents\": [\n    {\n      \"id\": \"primary\",\n      \"model\": \"claude-opus-4-6\",\n      \"memoryFile\": \"~/.openclaw/workspace/MEMORY.md\",\n      \"notesFile\": \"~/.openclaw/workspace/NOTES.md\"\n    }\n  ],\n  \"channels\": {\n    \"telegram\": {\n      \"enabled\": true,\n      \"token\": \"$TELEGRAM_BOT_TOKEN\",\n      \"allowedUsers\": [\"@yourusername\"]\n    },\n    \"discord\": {\n      \"enabled\": true,\n      \"token\": \"$DISCORD_BOT_TOKEN\",\n      \"allowedChannels\": [\"agent-commands\"]\n    }\n  },\n  \"skills\": {\n    \"directories\": [\"~/.openclaw/workspace/skills/\"]\n  }\n}\n</code></pre>\n<h2>Essential Commands</h2>\n<pre><code class=\"language-bash\"># Status and health\nopenclaw status\nopenclaw health\nopenclaw gateway status\nopenclaw doctor\nopenclaw logs --follow\n\n# Gateway control\nopenclaw gateway start\nopenclaw gateway stop\nopenclaw gateway restart\nopenclaw gateway install        # install as system service\n\n# Channels\nopenclaw channels status --probe\nopenclaw channels login --channel whatsapp\nopenclaw pairing list telegram\n\n# Skills\nopenclaw skills list\nopenclaw skills reload\n</code></pre>\n<h2>VPS Installation</h2>\n<pre><code class=\"language-bash\"># Prerequisites\ncurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -\nsudo apt-get install -y nodejs\n\n# Install OpenClaw\nnpm install -g @openclaw/cli\n\n# Initialize\nopenclaw init\nopenclaw setup\n\n# Verify\nopenclaw doctor\n</code></pre>\n<h2>Security: Tailscale + UFW Lockdown</h2>\n<p>Never expose the OpenClaw gateway publicly. Use Tailscale as the control plane:</p>\n<pre><code class=\"language-bash\"># Install Tailscale\ncurl -fsSL https://tailscale.com/install.sh | sh\nsudo tailscale up --authkey=tskey-...\n\n# Lock down with UFW\nsudo ufw default deny incoming\nsudo ufw allow ssh\nsudo ufw allow in on tailscale0      # allow Tailscale traffic\nsudo ufw enable\n\n# Verify gateway is only reachable via Tailscale\ncurl http://100.x.x.x:18789/health   # Tailscale IP\n</code></pre>\n<h2>Memory Files</h2>\n<p>The agent reads and writes these files to maintain context across sessions:</p>\n<pre><code class=\"language-markdown\">&#x3C;!-- MEMORY.md — Long-term knowledge -->\n# Agent Memory\n\n## Projects\n- Project X: Next.js app at /home/user/projects/x\n\n## Preferences\n- Always use TypeScript\n- Deploy to Vercel\n</code></pre>\n<pre><code class=\"language-markdown\">&#x3C;!-- NOTES.md — Working notes and scratchpad -->\n# Current Notes\n...\n</code></pre>\n<pre><code class=\"language-markdown\">&#x3C;!-- HEARTBEAT.md — Cron status and last actions -->\n# Heartbeat Log\nLast ping: 2026-05-12T10:00:00Z\nStatus: active\n</code></pre>\n<h2>Skills</h2>\n<p>Skills are markdown files that extend agent capabilities:</p>\n<pre><code class=\"language-markdown\">&#x3C;!-- ~/.openclaw/workspace/skills/web-search.md -->\n---\nname: web-search\ndescription: Search the web and return summarized results\n---\n\n# Web Search\n\nWhen the user asks to search the web, use Brave Search API:\n\n## Instructions\nCall: GET https://api.search.brave.com/res/v1/web/search?q={query}\nHeader: X-Subscription-Token: $BRAVE_API_KEY\nReturn top 3 results with title, url, and snippet.\n</code></pre>\n<h2>Cron Jobs</h2>\n<pre><code class=\"language-json5\">{\n  \"cron\": [\n    {\n      \"schedule\": \"0 9 * * 1-5\",      // 9am weekdays\n      \"message\": \"Morning briefing: summarize pending tasks from NOTES.md\",\n      \"channel\": \"telegram\"\n    },\n    {\n      \"schedule\": \"*/30 * * * *\",     // every 30 minutes\n      \"message\": \"Heartbeat check: update HEARTBEAT.md with status\",\n      \"channel\": \"internal\"\n    }\n  ]\n}\n</code></pre>\n<h2>Triage Checklist for Broken Gateway</h2>\n<p>Before changing anything, collect:</p>\n<pre><code class=\"language-bash\">df -h /                              # disk usage\nps aux | grep openclaw               # active processes\nnetstat -tlnp | grep 18789           # gateway port\ntailscale status                     # Tailscale connectivity\nsudo ufw status                      # firewall rules\nopenclaw --version                   # installed version\nopenclaw doctor                      # health report\n</code></pre>\n<p>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.</p>\n<h2>Model Routing</h2>\n<pre><code class=\"language-json5\">{\n  \"agents\": [\n    {\n      \"id\": \"primary\",\n      \"model\": \"claude-opus-4-6\",    // heavy reasoning tasks\n      \"fallback\": \"claude-haiku-4-5\" // heartbeat, simple checks\n    }\n  ]\n}\n</code></pre>\n<p>Use Gemini CLI for lightweight heartbeat work to avoid Anthropic usage on routine checks.</p>\n<h2>Common Issues</h2>\n<p>| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Gateway not responding | Port 18789 blocked | Check UFW, ensure Tailscale IP allowed |\n| Telegram not pairing | Bot token expired | Regenerate via BotFather, update config |\n| Skills not loading | Wrong directory path | Verify <code>skills.directories</code> in config |\n| High token usage | Too many cron tasks | Add Gemini fallback for routine checks |\n| Memory not persisting | File permissions | <code>chmod 644 ~/.openclaw/workspace/*.md</code> |</p>\n"}