Skip to content

pottertech/openclaw-secure-start

BranchesTags

Repository files navigation

OpenClaw Secure Start 🦞🔒

Make OpenClaw secure BEFORE you run it for the first time.

What This Is

This repo adds a security layer to your OpenClaw installation. It runs after you install OpenClaw, but before you start using it.

Think of it like: Installing seatbelts and airbags in a car before you drive it.

Why This Exists

OpenClaw is powerful. It can:

  • Access your files
  • Run commands on your computer
  • Send messages from your accounts
  • Make phone calls

That's great... but also risky if not secured properly.

This tool gives you secure defaults so you start safe, not sorry.

Choose Your Setup

Pick the section that matches where you're installing OpenClaw:

  • 🏠 Home / Private Network Setup

    • Personal laptop/desktop
    • Home server (behind router)
    • Private/dynamic IP behind NAT
    • Easiest and safest option for beginners

  • 🍓 Raspberry Pi Setup

    • Raspberry Pi 3/4/5 (ARM architecture)
    • Home automation hub
    • Always-on low-power server
    • Great for 24/7 Voice Agents

  • 🌐 VPS / Public Server Setup

    • Hostinger, DigitalOcean, AWS, Linode, etc.
    • Public IP address
    • Requires extra hardening (VPN mandatory)
    • For advanced users who need 24/7 uptime

🏠 Home / Private Network Setup

Best for: Personal use, home automation, learning OpenClaw

Why this is safer:

  • Your router/firewall blocks incoming connections
  • Private IP address (192.168.x.x, 10.x.x.x)
  • Only people on your WiFi can reach OpenClaw

Quick Start (Home)

Step 1: Install OpenClaw

curl -fsSL https://openclaw.ai/install.sh | bash

Step 2: Download This Security Repo

git clone https://github.com/pottertech/openclaw-secure-start.git
cd openclaw-secure-start

Step 3: Review and Edit Defaults

Check the secure defaults:

cat defaults/clawdbot.json      # Gateway settings
cat defaults/tool-policy.json   # What tools are allowed

What to verify in defaults/clawdbot.json:

{
  "gateway": {
    "bind": "127.0.0.1"   // ✅ Keep this - localhost only
  }
}

Keep 127.0.0.1 - this means OpenClaw only listens on your computer, not the internet.

Step 4: Run Security Hardening

./install.sh

Step 5: Choose Your Gateway Channel

Recommended (pick one):

Option A: WhatsApp ⭐ Easiest for most people

# During clawdbot setup:
# 1. Choose WhatsApp as your channel
# 2. Link your WhatsApp account (scan QR code)
# 3. Set DM policy to "allowlist" 
# 4. Add only YOUR phone number to the allowlist

Why WhatsApp: Most people already have it, reliable, works globally

Option B: Telegram

# During clawdbot setup:
# 1. Create Telegram bot via @BotFather
# 2. Get bot token
# 3. Set DM policy to "allowlist"
# 4. Add only YOUR Telegram user ID to the allowlist

Why Telegram: More private, no phone number needed for bot

⚠️ CRITICAL: Set channel privacy to "allowlist"

  • Never leave DMs open to "everyone"
  • Only allow YOUR phone number / Telegram ID
  • Prevents strangers from accessing your OpenClaw

Step 6: Setup OpenClaw

clawdbot setup

Done! Your home OpenClaw is secure and ready.

🍓 Raspberry Pi Setup

Best for: Home automation, always-on voice agents, IoT projects

Why Raspberry Pi is great for OpenClaw:

  • Low power consumption (runs 24/7 cheaply)
  • ARM architecture (lightweight, efficient)
  • GPIO access for hardware projects
  • Perfect for Brodie Foxworth voice agents
  • Private home network (like Home setup)

⚠️ Tailscale recommended - Pi often has dynamic IP from router

Quick Start (Raspberry Pi)

Step 1: Install Node.js on Raspberry Pi

Raspberry Pi OS doesn't include Node.js by default:

# Method 1: Using NodeSource (recommended)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt install -y nodejs

# Method 2: Using nvm (if you prefer)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20

# Verify installation
node --version  # Should show v20.x.x
npm --version

Step 2: Install OpenClaw

curl -fsSL https://openclaw.ai/install.sh | bash

Note: ARM architecture installs may take longer. Be patient!

Step 3: Install Tailscale (Strongly Recommended)

Your Pi probably gets a dynamic IP from your router. Tailscale gives it a stable address:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# Follow auth link in browser

Get your Tailscale IP:

tailscale ip -4
# Returns: 100.x.x.x

Step 4: Download This Security Repo

git clone https://github.com/pottertech/openclaw-secure-start.git
cd openclaw-secure-start

Step 5: Edit Defaults for Raspberry Pi

Choose your binding based on access needs:

Option A - Local access only:

{
  "gateway": {
    "bind": "127.0.0.1"   // ← Only accessible from Pi itself
  }
}

Option B - Home network access (no Tailscale):

{
  "gateway": {
    "bind": "192.168.x.x"  // ← Your Pi's local IP (check with: hostname -I)
  }
}

Option C - Tailscale access (recommended):

{
  "gateway": {
    "bind": "100.x.x.x"  // ← Your Tailscale IP (accessible from anywhere via VPN)
  }
}

Step 6: Run Security Hardening

./install.sh

On Pi, you might see ARM-related warnings. These are normal - OpenClaw works fine on ARM.

Step 7: Choose Your Gateway Channel

Same options as Home setup - WhatsApp or Telegram recommended.

Special Pi consideration:

  • WhatsApp QR code scanning might be easier on your phone than the Pi terminal
  • Use ssh -X or VNC if you need GUI for setup

Set DM policy to "allowlist" with only YOUR number.

Step 8: Setup OpenClaw

clawdbot setup

Tip: First startup on Pi may take 30-60 seconds. Be patient with ARM!

Done! Your Raspberry Pi OpenClaw is ready for 24/7 duty.

Raspberry Pi Specific Considerations

Power:

  • Use a quality power supply (3A for Pi 4, 2.5A for Pi 3)
  • Enable watchdog to auto-restart if frozen
  • Consider UPS hat for clean shutdowns

Storage:

  • SD cards wear out. Use high-endurance or SSD if possible
  • Move ~/.clawdbot to external drive if heavy I/O

Temperature:

# Check if throttling (bad!)
vcgencmd get_throttled
# 0x0 = good, anything else = check cooling

Auto-start on boot:

# Add to crontab (optional)
sudo crontab -e
# Add: @reboot /usr/bin/clawdbot gateway start

GPIO tools (optional): If you want OpenClaw to control hardware:

{
  "elevatedTools": {
    "enabled": true,
    "tools": ["exec"],
    "requireApproval": true
  }
}

Then use exec to run raspi-gpio or Python scripts.

🌐 VPS / Public Server Setup

Best for: 24/7 automations, always-on voice agents, production workloads

⚠️ WARNING: This is more dangerous

  • Your server has a public IP anyone can reach
  • Requires VPN (Tailscale/WireGuard) - mandatory
  • Needs firewall configuration (UFW)
  • Must read full VPS security guide

Prerequisites (MANDATORY)

Before starting:

  1. Read docs/vps-security.md completely
  2. Install Tailscale VPN on your server
  3. Basic Linux knowledge (you'll use command line)

Quick Start (VPS)

Step 1: Install Tailscale VPN (REQUIRED)

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# Auth with your Tailscale account

Get your Tailscale IP:

tailscale ip -4
# Returns: 100.x.x.x (save this!)

Step 2: Install OpenClaw

curl -fsSL https://openclaw.ai/install.sh | bash

Step 3: Download Security Repo

git clone https://github.com/pottertech/openclaw-secure-start.git
cd openclaw-secure-start

Step 4: Edit Defaults for VPS

CRITICAL: Change gateway binding to VPN IP

Edit defaults/clawdbot.json:

{
  "gateway": {
    "bind": "100.x.x.x"   // ← Replace with YOUR Tailscale IP
  }
}

⚠️ NEVER use 0.0.0.0 - it exposes OpenClaw to the entire internet!

Step 5: Run Install Script

./install.sh

The script detects VPS mode and warns you:

  • ✅ Creates secure directories
  • ✅ Copies VPN-tuned configs
  • ⚠️ Reminds you about firewall/fail2ban

Step 6: Configure Firewall

sudo apt install ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh           # Don't lock yourself out!
sudo ufw allow in on tailscale0  # Allow from VPN only
sudo ufw enable

Also install fail2ban:

sudo apt install fail2ban
sudo systemctl enable fail2ban

Step 7: Choose Your Gateway Channel

Same options as home setup, but with extra security:

WhatsApp (Recommended):

  • Link your WhatsApp account
  • Set DM policy to "allowlist"
  • Add ONLY your phone number
  • Consider a separate WhatsApp number just for OpenClaw

Telegram:

  • Create dedicated bot for OpenClaw
  • Set DM policy to "allowlist"
  • Add only YOUR user ID
  • Most private option for VPS

Extra VPS Precaution:

  • Set groupPolicy to "closed" (no group access)
  • Keep dmPolicy as "allowlist" (only you)
  • Never enable "everyone" on a public server

Step 8: Setup OpenClaw

clawdbot setup

Step 9: Run Security Audit

clawdbot security audit --deep

Fix any warnings immediately.

Done! Your VPS OpenClaw is secure and hardened.

📋 Post-Installation Checklist

No matter which setup you chose:

  • Verified gateway binding (127.0.0.1 home / Tailscale IP VPS)
  • Set channel DM policy to "allowlist" (not "open")
  • Added only MY number/ID to allowlist
  • Set group policy to "closed" (VPS) or appropriate (home)
  • Ran clawdbot security audit --deep
  • Fixed any audit warnings
  • Stored API keys in ~/.clawdbot/credentials/ (not in git)
  • Tested that elevated tools work correctly

⚙️ What to Edit in Defaults

Gateway Binding (CRITICAL)

Value When to Use Security
127.0.0.1 Home laptop/desktop ✅ Safest - only on this computer
100.x.x.x VPS with Tailscale ✅ Safe - VPN only
10.x.x.x Private network ✅ Safe if behind firewall
0.0.0.0 ❌ NEVER USE ❌ Exposes to entire internet

In defaults/clawdbot.json:

{
  "gateway": {
    "bind": "127.0.0.1"   // ← Change based on your setup
  }
}

Tool Policy

Start conservative in defaults/tool-policy.json:

Safe to start with:

{
  "allowedTools": [
    "read",        // Read files
    "write",       // Write files  
    "edit",        // Edit files
    "web_search",  // Search web
    "web_fetch"    // Fetch web pages
  ]
}

Add elevated tools only if needed:

{
  "elevatedTools": {
    "enabled": true,
    "tools": ["exec"],       // Shell commands - dangerous!
    "requireApproval": true  // ← Always require approval
  }
}

📦 What's in This Repo

openclaw-secure-start/
├── LICENSE
├── CHANGELOG.md
├── README.md              ← This file (setup guide)
├── QUICKSTART.md          ← One-page cheat sheet
├── MIGRATION.md           ← Move from unsafe → safe
├── TROUBLESHOOTING.md     ← Common problems
├── Makefile               ← Common commands
├── install.sh             ← Main hardening script
│
├── defaults/              ← Secure default configurations
│   ├── clawdbot.json      ← Gateway settings (EDIT THIS)
│   └── tool-policy.json   ← Tool allowlist (EDIT THIS)
│
├── hardening/             ← Security scripts
│   └── fix-permissions.sh ← Fix file permissions
│
├── docs/
│   ├── security-tips.md   ← Ongoing best practices
│   ├── vps-security.md    ← ⚠️ MANDATORY for VPS
│   ├── raspberry-pi.md    ← Complete Pi guide
│   └── audit-example.md   ← Good/bad/critical audit outputs
│
└── examples/
    ├── whatsapp-secure.json
    ├── telegram-secure.json
    ├── tailscale-setup.md
    └── README.md

🔄 Switching Between Setups

Home → VPS: Need to move to a server?

  1. Setup VPS with fresh OpenClaw install
  2. Run this security repo with VPS settings
  3. Re-link WhatsApp (old link won't work)
  4. Copy your credentials (API keys only, not state)

VPS → Home: Moving back to personal computer?

  1. Install OpenClaw on new machine
  2. Run this repo with home settings (127.0.0.1)
  3. Re-link messaging channels
  4. Transfer credentials safely

🆘 Troubleshooting

"clawdbot not found"

curl -fsSL https://openclaw.ai/install.sh | bash

"~/.clawdbot already exists"

This is a fresh-install script. For existing setups, backup first:

cp -r ~/.clawdbot ~/.clawdbot.backup

Permission denied

chmod +x install.sh
chmod +x hardening/fix-permissions.sh

VPS warnings about public IP

Normal! The script detected you're on a server. Read docs/vps-security.md carefully.

❌ What This Is NOT

  • ❌ Not the OpenClaw source code (see openclaw)
  • ❌ Not a replacement for OpenClaw
  • ❌ Not automatic undo for security mistakes
  • ❌ Not hacking or penetration testing tools
  • ❌ Not a substitute for reading security docs

This is: A security hardening wrapper that makes OpenClaw safer from day one.

🔐 Security Principles

  1. Least Privilege — Give minimum access needed
  2. Fail Closed — If unsure, disable it
  3. Audit Everything — Run clawdbot security audit regularly
  4. No Secrets in Repos — API keys stay in ~/.clawdbot/credentials/
  5. VPN First — Public servers MUST use Tailscale/WireGuard
  6. Never 0.0.0.0 — Don't expose to internet without protection

📚 More Resources

🙏 Credits

Created by Skip Potter (@pottertech)
For the Potter's Quill AI automation stack
Making AI agents safer for everyone. 🦞🔒

Remember: Security is a journey, not a destination. Stay safe!

About

Security hardening that runs AFTER OpenClaw install but BEFORE first run. Secure-by-default setup.

Resources

Readme

License

MIT license
Activity

Stars

25 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

No contributors

Languages