Getting Started: From Zero to Running AI Agent¶
Step-by-step setup with security hardening, channel configuration, and 24/7 always-on operation. Community-vetted.
Last updated: February 14, 2026
Table of Contents¶
- Choose Your Path
- Quick Start (10 Minutes)
- VPS Deployment (Recommended for 24/7)
- Channel Setup (Telegram, WhatsApp, Slack, Discord)
- Security Hardening (Do This Before Going Live)
- Common Pitfalls (What People Get Wrong)
- 24/7 Always-On Operation
- First Automations
- Recommended Skills
- Mac Local Setup
- Team Deployment
- Troubleshooting
Choose Your Path¶
| Goal | Time | Cost | Path |
|---|---|---|---|
| Try it out (quickest) | 10 min | API key only | Quick Start |
| Personal always-on agent | 15 min | $0 hardware + API | Local Setup (Recommended) |
| Team/remote agent | 30 min | $4/mo VPS + API | VPS Deployment |
| Local Mac + local models | 30 min | Hardware + API | Mac Local Setup |
| Team deployment | 1-2 hrs | VPS + API | Team Deployment |
Community consensus (Feb 2026): Local setup is recommended over VPS for most users. It's more secure by default, easier to integrate with your workflow, and doesn't require firewall/SSH expertise. VPS is only better if you need 24/7 uptime without leaving hardware on, or are deploying for a team. See Local vs VPS debate for full analysis. Source: Alex Finn
Quick Start (10 Minutes)¶
Prerequisites¶
- Node.js 22+ (
node --versionto check) - An LLM API key -- Anthropic recommended: https://console.anthropic.com
Install & Run¶
# Install (pick one)
curl -fsSL https://openclaw.ai/install.sh | bash # Official installer
npm install -g openclaw@latest # Via npm
# Run the setup wizard (walks you through everything)
openclaw onboard --install-daemon
# Verify it's running
openclaw gateway status
# Open the web dashboard
openclaw dashboard
# -> http://127.0.0.1:18789
Minimal Config (Budget-Friendly)¶
The wizard creates ~/.openclaw/openclaw.json. You can also create it manually.
Free setup (OpenRouter -- no credit card):
{
"env": { "OPENROUTER_API_KEY": "sk-or-your-key" },
"agents": {
"defaults": {
"model": {
"primary": "openrouter/moonshotai/kimi-k2.5",
"fallbacks": ["openrouter/google/gemini-2.5-flash:free"]
},
"heartbeat": {
"model": "openrouter/google/gemini-2.5-flash-lite:free"
}
}
}
}
Google Gemini free tier (1,500 req/day):
{
"env": { "GOOGLE_API_KEY": "your-gemini-api-key" },
"agents": {
"defaults": {
"model": { "primary": "google/gemini-2.5-flash" }
}
}
}
Premium (if you have budget):
Get an OpenRouter key at https://openrouter.ai (free, no credit card). Get a Gemini key at https://aistudio.google.com. Anthropic API at https://console.anthropic.com (pay-per-use -- NOT your subscription).
Local Setup (Recommended)¶
Source: Alex Finn -- DO NOT use a VPS
The simplest, most secure way to run OpenClaw. Works on any computer -- Mac Mini, old laptop, even a $75 Raspberry Pi.
Why Local?¶
- Secure by default -- Apple/Windows firewalls protect you out of the box
- One terminal command -- easier than VPS despite what sponsored videos claim
- Full integration -- AirDrop files, see it working, drag and drop
- Your data stays local -- no cloud provider has access
- No monthly hosting cost -- $0 after hardware purchase
Setup (Any Device)¶
# 1. Go to openclaw.ai, copy the install command, paste in terminal
curl -fsSL https://openclaw.ai/install.sh | bash
# 2. Run onboarding wizard
openclaw onboard --install-daemon
# Choose: Yes (acknowledge risks) → Quick Start → Choose AI provider
AI Provider Setup¶
Premium (Anthropic -- $200/mo subscription):
1. Choose "Anthropic" → "Anthropic token"
2. Select "Run Claude setup token elsewhere"
3. Open a second terminal, paste: claude setup token
4. Log into your Anthropic account
5. IMPORTANT: Copy the token to Notepad first. Remove ALL line breaks so it's one continuous line. Then paste.
Budget (Kimi K2.5 -- ~$5/mo): 1. Choose Moonshot in the provider menu 2. Enter your Moonshot API key 3. Check for free NVIDIA Kimi K2.5 deals: Google "nvidia kimi k2.5 free"
Messaging Channel¶
Choose Telegram (most customization, threading, chunking). The wizard walks you through creating a bot via @BotFather.
Post-Setup: Enable Hidden Memory Settings¶
Two settings are OFF by default that dramatically improve recall:
"Enable memory flush so important context survives compaction"
"Enable session memory search so you can search through all our past conversations"
See Power User Guide -- Hidden Memory Settings for details.
Post-Setup: Model Routing¶
Don't waste expensive tokens on everything. Set up the brain + muscles architecture:
"Use Opus 4.6 only for our conversations. Use Codex for coding. Use Haiku 4.5
for heartbeat checks. Use Perplexity for web search via OpenRouter."
See Power User Guide -- Model Routing for the full setup.
Security Notes for Local¶
- Fresh device: Secure by default (no existing accounts to compromise)
- Used device: WIPE it first. Don't install on a machine with existing sensitive accounts.
- Old laptop: Great option -- wipe it, install OpenClaw, dedicated AI machine for $0
VPS Deployment¶
Warning: VPS requires technical security knowledge. By default, VPS instances are not secure -- thousands of exposed OpenClaw instances have been found via Shodan/Censys scans with full credentials accessible. Only use VPS if you can configure firewalls, SSH, and network security properly. Source: Alex Finn
Why VPS? Agent runs 24/7 without hardware being on. Team deployment. $4-6/month.
Step 1: Choose a VPS Provider¶
| Provider | Price | Specs | Notes |
|---|---|---|---|
| Hetzner CX22 | ~$4/mo | 2 vCPU, 4GB RAM, 40GB NVMe | Community favorite. Best value. |
| Contabo | $4.95/mo | 3 vCPU, 8GB RAM, 75GB NVMe | Best specs/dollar |
| DigitalOcean | $6-12/mo | 1-2 vCPU, 1-2GB RAM | 1-Click app. $200 credit with code OPENCLAW |
| Vultr | $5/mo | 1 vCPU, 1GB RAM | 25+ locations |
| Oracle Cloud | $0/mo forever | 4 ARM, 24GB RAM, 200GB SSD | Free tier. Complex signup. |
Minimum specs: 2GB RAM, 2 vCPU, SSD storage. 4GB recommended.
Step 2: Server Setup¶
Community consensus (Feb 2026): Docker is NOT required for OpenClaw. Direct npm install is simpler, faster, and avoids gateway token loops and compose complexity. Only use Docker if you need tool sandboxing or browser automation isolation. Source: Multiple community voices including @HappyGezim (LobsterFarm.ai)
# SSH into your VPS
ssh root@your-vps-ip
# Create a dedicated user (never run as root)
adduser openclaw
usermod -aG sudo openclaw
su - openclaw
# Install Node.js 22+
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
# Install OpenClaw (Docker NOT required)
npm install -g openclaw@latest
# Optional: Install Docker only if you need sandboxing
# curl -fsSL https://get.docker.com | sh
# sudo usermod -aG docker openclaw
Step 3: Configure¶
openclaw onboard --install-daemon
# The wizard walks through:
# 1. AI provider (enter your Anthropic API key)
# 2. Model selection (claude-sonnet-4-5 for budget, opus-4-6 for quality)
# 3. Gateway port (default 18789)
# 4. Channel selection (Telegram is easiest to start)
Step 4: Run as Systemd Service (Always-On)¶
# Create service file
sudo cat > /etc/systemd/system/openclaw.service << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network.target docker.service
[Service]
Type=simple
User=openclaw
ExecStart=/usr/bin/openclaw gateway
Restart=always
RestartSec=5
Environment=NODE_ENV=production
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw # Verify it's running
Step 5: Secure Remote Access¶
# Option A: Tailscale (recommended -- zero config VPN)
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up
# Access dashboard at http://your-tailscale-ip:18789
# Option B: Caddy reverse proxy with HTTPS
sudo apt install caddy
# Configure Caddyfile for your domain
Channel Setup¶
Telegram (Start Here -- Easiest)¶
- Open Telegram, find @BotFather
- Send
/newbot - Choose a display name (e.g., "My AI Agent")
- Choose a username (must end in
_bot, e.g.,myagent_bot) - Copy the token:
123456789:ABCdefGHI... - Configure:
- Find your bot on Telegram, send
/start - Enter the 6-digit pairing code in your terminal
WhatsApp (QR Code Pairing)¶
Warning: This links to your WhatsApp number. The agent sees ALL your messages. Use a dedicated number.
- Access dashboard:
http://127.0.0.1:18789 - Navigate: Channels -> Add Channel -> WhatsApp
- QR code displays on screen
- On phone: WhatsApp -> Settings -> Linked Devices -> Link a Device
- Scan the QR code
WhatsApp uses the Baileys library (reverse-engineered, not official API). Connections can drop -- restart gateway if it disconnects.
Slack (Socket Mode)¶
- Go to https://api.slack.com/apps -> Create New App -> From scratch
- Enable Socket Mode: Settings -> Socket Mode -> toggle ON
- Generate App-Level Token with scope
connections:write-> copyxapp-...token - Add Bot Token Scopes under OAuth & Permissions:
chat:write,channels:history,channels:read,im:historyusers:read,app_mentions:read,reactions:read- Subscribe to Bot Events:
app_mention,message.channels,message.im - Install App to workspace -> copy Bot Token (
xoxb-...) - Configure:
Discord¶
- Go to https://discord.com/developers/applications -> New Application
- Bot -> Add Bot -> enable Message Content Intent
- Copy bot token
- OAuth2 -> URL Generator -> select
botscope +Send Messages,Read Message History - Use generated URL to invite bot to your server
- Configure:
openclaw channel add discord --token YOUR_BOT_TOKEN
Security Hardening¶
Do this BEFORE going live. Not after.
Tier 1: Mandatory (15 minutes)¶
# 1. Firewall -- deny all incoming except SSH
sudo ufw default deny incoming
sudo ufw allow 22
sudo ufw enable
# 2. Bind gateway to localhost only (NEVER 0.0.0.0)
# In openclaw.json: "gateway": { "host": "127.0.0.1" }
# 3. Set DM policy to pairing (requires approval codes)
# In openclaw.json: "channels": { "dmPolicy": "pairing" }
# 4. Run security audit
openclaw security audit --deep
openclaw doctor
# 5. Set file permissions on config (contains API keys)
chmod 600 ~/.openclaw/openclaw.json
# 6. Verify Node.js version (CVE-2026-21636 patch)
node --version # Must be 22.12.0+
Tier 2: Recommended (30 minutes)¶
- Install Tailscale for remote access instead of exposing ports
- Enable Docker sandbox for tool execution:
"sandbox": { "mode": "non-main" } - Use burner accounts only -- never connect primary Gmail, banking, or cloud storage
- Set API spending caps at provider level (Anthropic Console -> Usage -> Set limit)
- Disable mDNS in gateway config
- Allowlist tools explicitly in config (
tools.allow)
Tier 3: Advanced (1-2 hours)¶
- Run OpenClaw in Docker container with restricted networking
- Use LiteLLM as credential broker (proxy injects API keys so OpenClaw never sees them)
- Set up Squid proxy with domain allowlist for all outbound traffic
- Separate agents by risk level (read-only agent vs shell-access agent)
- Monthly token rotation for all API keys
Critical CVEs¶
| CVE | Severity | Fix |
|---|---|---|
| CVE-2026-25253 | 8.8 (High) | Update to latest OpenClaw. WebSocket token exfiltration. |
| CVE-2026-21636 | High | Node.js 22.12.0+. Permission bypass. |
Common Pitfalls¶
What people get wrong (sourced from Reddit, GitHub Issues, guides):
| Mistake | What Happens | Fix |
|---|---|---|
Binding to 0.0.0.0 |
Gateway exposed to entire internet | Always bind to 127.0.0.1 |
| DM policy set to "open" | Anyone can control your agent | Set dmPolicy: "pairing" |
| Using personal WhatsApp | Agent responds to ALL your messages | Use a dedicated number/SIM |
| Skipping Docker sandbox | Prompt injection = arbitrary commands on host | Enable sandbox mode |
| Installing untrusted skills | 26% of ClawHub skills had vulnerabilities | Review source code first |
| No API spend limits | Agent burns through credits in overnight loops | Set hard cap at provider level |
| Running as root | Container escape = full system compromise | Create dedicated openclaw user |
| Using old Node.js | CVE-2026-21636 permission bypass | Requires 22.12.0+ |
| Connecting real accounts | Agent accesses primary email, cloud storage | Use burner accounts only |
| No firewall | Ports exposed publicly | ufw default deny incoming |
24/7 Always-On Operation¶
The $500 Overnight Bill Is Real¶
Real examples from the community: - Heartbeat asking "Is it daytime yet?" 25x overnight: $18.75/night - "Simple scheduled tasks" overnight: 5.7M tokens ($200) between 10pm-11am - Misconfigured compaction: $40 in tokens overnight
Cost Control (Non-Negotiable)¶
- Set hard spending cap at API provider level -- this is the #1 rule
- Use cheap models for background tasks:
- Interactive: Claude Opus 4.6 ($5-25/M tokens)
- Background/overnight: Kimi K2.5 ($0.10/M cached) or Haiku 4.5 ($1-5/M)
- Restrict cron jobs to useful hours -- no 3am tasks unless needed
- Batch checks into heartbeat instead of multiple independent cron jobs
- Set alerts at 50%, 75%, 90% of monthly budget
- Monitor weekly -- audit token usage for redundant calls
Heartbeat vs Cron¶
| Feature | Heartbeat | Cron Job |
|---|---|---|
| Timing | Interval (default 30 min) | Exact schedule (crontab syntax) |
| Session | Runs in main session | Can run isolated |
| Cost risk | Lower (batched checks) | Higher (each runs independently) |
| Config | HEARTBEAT.md file | openclaw cron add command |
Monitoring¶
| Tool | Cost | Use For |
|---|---|---|
| Provider dashboard | Free | Token usage tracking |
| Uptime Robot | Free (50 monitors) | Heartbeat/uptime monitoring |
| Grafana Cloud | Free (10K metrics) | Cost dashboards |
openclaw gateway status |
Free | Quick health check |
First Automations¶
Morning Briefing (Weekdays 7am)¶
openclaw cron add \
--name "Morning Briefing" \
--cron "0 7 * * 1-5" \
--message "Give me today's briefing: weather, calendar events, top 5 urgent emails, and any Slack messages I need to respond to"
Email Triage (Every 30 Minutes, Business Hours Only)¶
openclaw cron add \
--name "Email Triage" \
--cron "*/30 8-18 * * 1-5" \
--message "Check my inbox. Categorize new emails as urgent/normal/low. Draft responses for urgent ones. Send me a Slack summary."
End-of-Day Summary (Weekdays 6pm)¶
openclaw cron add \
--name "EOD Summary" \
--cron "0 18 * * 1-5" \
--message "Summarize today: emails processed, meetings held, tasks completed, outstanding items for tomorrow"
Recommended Skills¶
Start With These (Beginner-Friendly)¶
| Skill | What It Does | Risk Level |
|---|---|---|
| Built-in: cron | Schedule recurring tasks | Low |
| Built-in: message | Push notifications to channels | Low |
| Built-in: browser | Browse the web, read pages | Medium |
| git-essentials | Git operations from chat | Low |
| task-status | Task/todo tracking | Low |
| coding-agent | Claude Code / Codex orchestration | Medium |
# Install community skills
npx clawhub@latest install git-essentials
npx clawhub@latest install task-status
npx clawhub@latest install coding-agent
Skills to AVOID as a Beginner¶
- Password manager skills -- "Once authorized, it has access to your entire vault"
- Shell/exec skills you don't understand
- Random ClawHub skills without reviewing source -- 26% had vulnerabilities (Cisco Talos audit)
- OAuth-heavy skills until you understand scoping
Mac Local Setup¶
For running local LLMs alongside OpenClaw (optional -- OpenClaw works fine with cloud APIs only).
# Install prerequisites
brew install node@22
brew install --cask docker # Optional, for sandboxing
# Install OpenClaw
npm install -g openclaw@latest
openclaw onboard --install-daemon
# (Optional) Install Ollama for local models
brew install ollama
ollama pull qwen2.5-coder:32b
ollama serve # localhost:11434
Configure hybrid mode (cloud primary, local fallback):
Team Deployment¶
Multi-Agent Profiles¶
# Create separate agents per function
openclaw profile create sales
openclaw profile create ops
openclaw profile create support
# Run each on different ports
openclaw --profile sales gateway --port 18790
openclaw --profile ops gateway --port 18791
openclaw --profile support gateway --port 18792
Per-Agent Configuration¶
Each profile gets its own workspace with AGENTS.md:
Sales Agent (~/.openclaw/profiles/sales/workspace/AGENTS.md):
You are the Sales Agent for [Company Name].
- Respond to incoming WhatsApp Business inquiries
- Qualify leads based on [criteria]
- Schedule demos via Calendly
- Escalate enterprise deals to human sales team
Ops Agent (~/.openclaw/profiles/ops/workspace/AGENTS.md):
You are the Operations Agent for [Company Name].
- Monitor Slack for @ops mentions
- Run deployment scripts when authorized
- Check server health and alert on issues
- Generate daily standup summaries
Reverse Proxy (Caddy)¶
sales.yourdomain.com {
reverse_proxy localhost:18790
}
ops.yourdomain.com {
reverse_proxy localhost:18791
}
support.yourdomain.com {
reverse_proxy localhost:18792
}
Troubleshooting¶
| Issue | Fix |
|---|---|
| Gateway won't start | Check node --version (need 22+) |
| WhatsApp disconnects | openclaw channel reconnect whatsapp or restart gateway |
| High API costs | Check dashboard token usage. Reduce cron frequency. Use cheaper model. |
| Skills not loading | Check ~/.openclaw/workspace/skills/ directory |
| Docker sandbox fails | Ensure Docker is running: docker ps |
| Can't access dashboard remotely | Set up Tailscale or reverse proxy with HTTPS |
| "Connection refused" on 18789 | Gateway bound to wrong interface. Check host in config. |
| Bot not responding | Check openclaw gateway status. Verify channel token is correct. |
Mobile & Remote Control¶
Control Methods (On the Go)¶
| Method | Platform | Best For |
|---|---|---|
| Telegram Bot | iOS/Android | Most popular. Full chat, /pair command, phone control |
| GoClaw App | iOS/Android | Free app, WebSocket to gateway, health monitoring |
| iOS/Android | QR code pairing, familiar interface | |
| Discord | iOS/Android | Server-based, multi-channel |
| Web Dashboard | Any browser | Full control via Tailscale/tunnel |
| Voice | iOS/macOS | "Hey Siri call Jarvis" → Twilio → OpenClaw |
iOS App (Alpha -- v2026.2.9)¶
OpenClaw shipped an alpha iOS app: - Pairs via Telegram setup-code - Connects to Gateway with reconnect support - Exposes device services: status, photos, contacts, calendar, reminders - Early Talk/Chat mode included - Foreground-only -- background not stable yet
Remote Dashboard Access¶
# Option A: Tailscale Serve (recommended -- private, zero config)
tailscale serve --bg 18789
# Access: http://your-machine.tailnet-name:18789
# Option B: SSH Tunnel (ad-hoc)
ssh -L 3000:127.0.0.1:18789 user@your-vps
# Option C: Cloudflare Tunnel (public with auth)
cloudflared tunnel --url http://localhost:18789
Never expose 0.0.0.0 directly. Always tunnel.
Mac Desktop App¶
- OpenClaw.app (official) -- Electron, menu bar, Voice Wake, remote gateway control
- CJ's Mac App (@cjsingg) -- "Cursor for my digital life," Electron + shadcn, control via Mac or Telegram/WhatsApp when away
Managed Hosting (Zero Setup)¶
If you don't want to manage infrastructure, several startups offer managed OpenClaw hosting:
| Service | Price | Deploy Time | Key Feature |
|---|---|---|---|
| Ampere.sh | Free + $500 Opus credits | 60 seconds | Chrome pre-configured, zero DevOps |
| LobsterFarm.ai | Varies | 1-click | Isolated Hetzner instances |
| MyClaw | TBD | Minutes | Private instance, context memory |
| ClawBox | $199 hardware | Plug & play | Pre-configured Jetson Orin Nano |
| OpenClawd | TBD | 1-click | Hardened security defaults, launched Feb 10, 2026 |
OpenClawd (launched Feb 10, 2026) is notable -- it's a managed hosting platform with built-in security addressing 63% of vulnerable instances. Targets users who "tried and failed to set up OpenClaw on their own."
Warning from creator: Peter Steinberger warns against quick-install services that may skip security docs. But these managed services handle security configuration for you.
Full managed hosting comparison: Twitter Community Insights -- Managed Hosting
Best Guides (External)¶
| Guide | Best For |
|---|---|
| freeCodeCamp Full Tutorial | Complete beginner walkthrough |
| Security Hardening Guide | 3-tier security hardening |
| DigitalOcean Tutorial | Production VPS setup |
| Official Docs | Reference documentation |
Next Steps¶
- Ultimate OpenClaw Setup -- Production configs, soul.md/agents.md templates, ClawRouter (saves 70%), token optimization, security checklist
- Power User Guide -- 9 core files, hidden memory settings, model routing, reverse prompting, self-built tooling
- Read the OpenClaw Complete Guide for architecture deep dive
- Review Security Hardening for enterprise checklist
- Explore the Hardware Guide if running local models
- Check the Model Landscape for latest model recommendations
- Set up Social Media Integrations for Twitter, Reddit, YouTube