How to Run OpenClaw Safely Across Platforms (Windows, macOS, Linux)

Running OpenClaw is not the same as launching a typical desktop app or SaaS tool. It’s an agentic system that stays active, listens for events, executes commands, and interacts with external services on your behalf. That means how you run it—where it lives, what it can access, and how it stays online—directly shapes both its usefulness and its risk profile.

Formerly known as Clawdbot (and briefly Moltbot), OpenClaw runs locally or on a server you control, rather than inside a managed cloud environment. This design gives users flexibility and transparency, but it also shifts operational responsibility to the person running it. There’s no managed runtime, no default guardrails, and no “set it and forget it” mode. Once OpenClaw is running, it behaves more like a long-lived service than a chat interface.

In this guide, we’ll focus specifically on how to run OpenClaw across common environments—from cloud deployments like DigitalOcean to local machines such as Mac minis, Windows PCs, and Linux servers. The goal isn’t to rush through commands, but to help you understand what’s actually happening when OpenClaw is running, what stays active in the background, and what trade-offs each environment introduces.

How to Run OpenClaw on Windows

Recommended Approach: Windows Subsystem for Linux (WSL2)

• OpenClaw is not recommended to run natively on Windows
• The official and most stable method is WSL2 with Ubuntu
• OpenClaw’s CLI, Gateway, and tooling run inside Linux
• WSL2 ensures compatibility with:
  
  • Node.js / Bun / pnpm
  • Linux binaries
  • Skills and system tooling
• Native Windows companion apps are planned, but not available yet
• WSL2 provides a full Linux environment with minimal setup

Step 1 — Install WSL2 and Ubuntu

• Open PowerShell as Administrator
• Install WSL2 with the default Ubuntu distribution:

wsl --install

Or install a specific Ubuntu version:

wsl --list --online
wsl --install -d Ubuntu-24.04

• Reboot Windows if prompted
• Official Microsoft guide: https://learn.microsoft.com/windows/wsl/install

Step 2 — Enable systemd (Required)

• Open your Ubuntu (WSL) terminal
• Enable systemd support:

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

• Shut down WSL from PowerShell:

wsl --shutdown

• Reopen Ubuntu
• Verify systemd is running:

systemctl --user status

Step 3 — Install OpenClaw Inside WSL

• Follow the Linux installation flow inside WSL
• Clone the OpenClaw repository:

git clone https://github.com/openclaw/openclaw.git
cd openclaw

• Install dependencies and build:

pnpm install
pnpm ui:build
pnpm build

• Start onboarding:

openclaw onboard

• This installs the CLI, UI, and prepares the Gateway

Step 4 — Install and Run the Gateway Service

• Inside WSL, install the Gateway as a service:

openclaw onboard --install-daemon

• Alternative options:

openclaw gateway install
openclaw configure

• Select Gateway service when prompted
• Repair or migrate the setup if needed:

openclaw doctor

Advanced — Expose OpenClaw Services Over LAN (Optional)

• WSL runs on a virtual network
• To access OpenClaw from another machine, ports must be forwarded
• The WSL IP changes after restarts, so rules may need refreshing

PowerShell (Admin) example:

$Distro = "Ubuntu-24.04"
$ListenPort = 2222
$TargetPort = 22

$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
if (-not $WslIp) { throw "WSL IP not found." }

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
  connectaddress=$WslIp connectport=$TargetPort

• Allow the port through Windows Firewall (one-time):

New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
  -Protocol TCP -LocalPort $ListenPort -Action Allow

• Refresh port forwarding after WSL restarts:

netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0
netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
  connectaddress=$WslIp connectport=$TargetPort

Important Notes for Windows Users

• SSH access targets the Windows host IP, not the WSL IP

Example:

ssh user@windows-host -p 2222

• Remote nodes must use a reachable Gateway URL‍
  
  • Avoid 127.0.0.1

Check status with:

openclaw status --all

• Use listenaddress=0.0.0.0 for LAN access
• Use 127.0.0.1 to keep services local only
• Scheduled Tasks can automate port refresh on login

Windows Companion App Status

• No native Windows companion app exists yet
• Contributions are welcome
• Current recommended setup remains WSL2 + Ubuntu

How to Run OpenClaw on macOS

macOS App Overview

• The macOS app is the menu-bar companion for OpenClaw
• It manages:
  
  • Local permissions
  • Gateway lifecycle
  • macOS-specific capabilities
• Acts as a node that exposes macOS features to OpenClaw
• Runs locally or connects to a remote Gateway

What the macOS App Does

• Displays native notifications and status in the menu bar
• Manages macOS permission prompts (TCC), including:
  
  • Notifications
  • Accessibility
  • Screen Recording
  • Microphone
  • Speech Recognition
  • Automation / AppleScript
• Runs or connects to the Gateway (local or remote)
• Exposes macOS-only tools:
  
  • Canvas
  • Camera
  • Screen Recording
  • system.run
• Starts or stops the local node host service based on mode
• Optionally hosts PeekabooBridge for UI automation
• Installs the global CLI (openclaw) via npm or pnpm
  
  • Bun is not recommended for Gateway runtime

Local vs Remote Mode

Local Mode (Default)

• Attaches to an existing local Gateway
• If none is running, enable it via launchd

Uses:

 openclaw gateway install

Remote Mode

• Connects to a Gateway over SSH or Tailscale
• Does not start a local Gateway
• Starts a local node host service
• Allows the remote Gateway to reach this Mac
• The macOS app is not a child process of the Gateway
  

Launchd Control (macOS)

• Gateway runs as a per-user LaunchAgent
• Default label:
  
  • bot.molt.gateway
• Profile-based label:
  
  • bot.molt.<profile>

Start Gateway

launchctl kickstart -k gui/$UID/bot.molt.gateway

Stop Gateway

launchctl bootout gui/$UID/bot.molt.gateway

• Replace label with bot.molt.<profile> when using named profiles
• Legacy com.openclaw.* agents still unload correctly

Install the LaunchAgent via:

openclaw gateway install

Node Capabilities (macOS)

• The macOS app registers as a node
• Common node commands include:

Canvas

canvas.present
canvas.navigate
canvas.eval
canvas.snapshot
canvas.a2ui.*

Camera

camera.snap
camera.clip

Screen

screen.record

System

• system.run
• system.notify
• Node reports a permissions map to the Gateway
• Agents decide allowed actions based on this map
  

Node Service and App IPC

• In Remote mode:
  
  • Headless node host service connects to Gateway via WebSocket
• system.run executes inside the macOS app
• Communication uses:
  
  • Unix Domain Socket (UDS)
  • Token authentication
  • HMAC validation
  • TTL enforcement
• Prompts and outputs remain inside the macOS app

Flow

• Gateway → Node Service (WebSocket)
• Node Service → macOS App (IPC)

Exec Approvals (system.run)

• Controlled from Settings → Exec Approvals in the macOS app

Rules stored locally at:

 ~/.openclaw/exec-approvals.json

Example Configurationa

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [
        { "pattern": "/opt/homebrew/bin/rg" }
      ]
    }
  }
}

• Allowlist entries match resolved binary paths
• Choosing “Always Allow” adds the command automatically
• Environment overrides are filtered:
  
  • PATH
  • DYLD_*
  • LD_*
  • NODE_OPTIONS
  • PYTHON*
  • PERL*
  • RUBYOPT

Deep Links (openclaw://)

• macOS app registers the openclaw:// URL scheme

Trigger an Agent

open 'openclaw://agent?message=Hello%20from%20deep%20link'

Supported Parameters

• message (required)
• sessionKey
• thinking
• deliver
• to
• channel
• timeoutSeconds
• key (unattended mode)

Safety Rules

• Without key: user confirmation required
• With a valid key: runs unattended (personal automation use)

Typical macOS Onboarding Flow

• Install and launch OpenClaw.app
• Complete permission checklist (TCC prompts)
• Confirm Local mode is active
• Ensure the Gateway is running
• Install CLI if terminal access is needed

Build and Development Workflow (Native)

Build macOS app:

 cd apps/macos
swift build
swift run OpenClaw

Package app:

 scripts/package-mac-app.sh

Debug Gateway Connectivity (macOS CLI)

• Test Gateway connectivity without launching the app

cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

Connect Options

• --url ws://host:port
• --mode local|remote
• --probe
• --timeout <ms>
• --json

Discovery Options

• --include-local
• --timeout <ms>
• --json
• Compare results with:

openclaw gateway discover --json

Remote Connection Plumbing (SSH Tunnels)

• Used in Remote mode
• Allows local UI to communicate with remote Gateway

Control Tunnel

• Purpose:
  
  • Health checks
  • Web chat
  • Config
  • Control-plane calls
• Local port:
  
  • Gateway default (18789)
• Remote port:
  
  • Same Gateway port on remote host

Behavior

• Stable local port
• Reuses healthy tunnels
• Restarts tunnels automatically if needed

SSH Shape

ssh -N -L <local>:127.0.0.1:<remote>

• Loopback hides real client IP
• Use direct WS/WSS transport to preserve client IP

How to Run OpenClaw on Android

Android Support Overview

• Android runs as a companion node app
• Android does not host the Gateway
• A running Gateway is required on:
  
  • macOS
  • Linux
  • Windows (via WSL2)
• Android connects to the Gateway over WebSocket
• Setup involves:
  
  • Gateway pairing
  • Network discovery
  • Node approval

System Control

• System services (launchd / systemd) live on the Gateway host
• Android does not manage the Gateway lifecycle
• Gateway management remains on the server or desktop machine

Connection Architecture

• Android Node App ⇄ Gateway
• Transport:
  
  • mDNS / NSD (LAN)
  • WebSocket
• Default Gateway endpoint:

ws://<gateway-host>:18789

• Pairing and authorization are Gateway-owned

Prerequisites

• A running Gateway on a “master” machine
• Android device or emulator can reach the Gateway:
  
  
  
  • Same LAN via mDNS / NSD
  • Same Tailscale tailnet (recommended)
  • Manual host + port (fallback)
    
    
• Ability to run the openclaw CLI on the Gateway host (local or SSH)

Step 1 — Start the Gateway

On the Gateway host:

 openclaw gateway --port 18789 --verbose

• Confirm logs show:

listening on ws://0.0.0.0:18789

• For tailnet-only setups:

Set gateway.bind to tailnet in:

 ~/.openclaw/openclaw.json

• Restart the Gateway or macOS menu-bar app

Step 2 — Verify Discovery (Optional)

From the Gateway host:

 dns-sd -B _openclaw-gw._tcp local

• Use this only for debugging mDNS visibility

Tailnet Discovery Across Networks

• Android mDNS does not cross networks
• For Android ⇄ Gateway across locations:
  
  • Use Wide-Area Bonjour / unicast DNS-SD
• Required steps:
  
  • Create a DNS-SD zone (example: openclaw.internal.)
  • Publish _openclaw-gw._tcp records
  • Configure Tailscale split DNS to point to this zone
• CoreDNS examples available in the Bonjour documentation

Step 3 — Connect from the Android App

• Open the Android OpenClaw app
• The app runs a foreground service:
  
  • Keeps Gateway connection alive
  • Shows a persistent notification
• Navigate to Settings
• Under Discovered Gateways:
  
  • Select your Gateway
  • Tap Connect
• If discovery fails:
  
  • Go to Advanced
  • Choose Manual Gateway
  • Enter host and port
  • Tap Connect
• After first successful pairing:
  
  • App reconnects automatically on launch
  • Uses last known Gateway or manual endpoint

Step 4 — Approve Pairing (Gateway CLI)

On the Gateway host:

openclaw nodes pendingopenclaw nodes approve <requestId>

• Pairing details are managed by the Gateway
  
  

Step 5 — Verify Node Connection

Check node status:

openclaw nodes status

Or via Gateway call:

 openclaw gateway call node.list --params "{}"

Step 6 — Chat and History

• Android uses the Gateway’s primary session key
• Chat history is shared across:
  
  • Android
  • Web Chat
  • Other clients
• Core actions:
  
  • History: chat.history
  • Send message: chat.send
  • Live updates (best-effort): chat.subscribe → event:"chat"

Step 7 — Canvas and Camera Capabilities

Gateway Canvas Host (Recommended)

• Use the Gateway canvas host for editable HTML/CSS/JS
• Canvas host:
  
  • Port: 18793

Create:

 ~/.openclaw/workspace/canvas/index.html

Navigate Android node (LAN):
‍

 openclaw nodes invoke \
  --node "<Android Node>" \
  --command canvas.navigate \
  --params '{"url":"http://<gateway-host>.local:18793/__openclaw__/canvas/"}'

Tailnet setups:

• Use MagicDNS name or tailnet IP

Example:

 http://<gateway-magicdns>:18793/__openclaw__/canvas/

• Canvas features:
  
  • Live reload on file changes

A2UI host at:

 http://<gateway-host>:18793/__openclaw__/a2ui/

Canvas Commands (Foreground Only)

• canvas.eval
• canvas.snapshot
• canvas.navigate
  
  • Use { "url": "" } or { "url": "/" } to return to scaffold
• Snapshot returns:
  
  • { format, base64 }
  • Default format: jpeg
• A2UI:
  
  • canvas.a2ui.push
  • canvas.a2ui.reset
  • Legacy alias: canvas.a2ui.pushJSONL

Camera Commands (Foreground Only)

• Permission-gated commands:
  
  • camera.snap (JPEG)
  • camera.clip (MP4)
• Parameters and helpers documented in the Camera node reference

How to Run OpenClaw on iOS

iOS Support Overview

• iOS app is currently in internal preview
• Not publicly distributed yet
• iOS runs as a companion node
• iOS does not host the Gateway
• Requires an active Gateway on:
  
  • macOS
  • Linux
  • Windows (via WSL2)

What the iOS App Does

• Connects to the Gateway over WebSocket
  
  • LAN or tailnet
• Exposes node capabilities:
  
  • Canvas rendering
  • Screen snapshot
  • Camera capture
  • Location access
  • Talk mode
  • Voice wake
• Receives node.invoke commands
• Reports node status events to the Gateway

Requirements

• Gateway running on a separate device
• Network connectivity via one of the following:
  
  • Same LAN using Bonjour
  • Tailnet using unicast DNS-SD (example domain: openclaw.internal.)
  • Manual host and port (fallback)
• Ability to run openclaw CLI on the Gateway host

Quick Start — Pair and Connect

Start the Gateway on the host machine:

 openclaw gateway --port 18789

• Open the iOS app
• Navigate to Settings
• Select a discovered Gateway
  
  • Or enable Manual Host and enter host + port

Approve pairing on the Gateway host:

openclaw nodes pending
openclaw nodes approve <requestId>

Verify the connection:

openclaw nodes status
openclaw gateway call node.list --params "{}"

Discovery Paths

Bonjour (LAN)

• Gateway advertises:
  
  • _openclaw-gw._tcp on local.
• iOS app automatically lists discovered Gateways

Tailnet (Cross-Network)

• Used when mDNS is blocked
• Requires:
  
  • Unicast DNS-SD zone (example: openclaw.internal.)
  • Tailscale split DNS
• CoreDNS examples available in Bonjour documentation

Manual Host and Port

• Enable Manual Host in Settings
• Enter:
  
  • Gateway hostname
    
    • Port (default: 18789)

Canvas and A2UI Support

• iOS node renders content using WKWebView
• Canvas controlled using node.invoke

Navigate to Canvas

openclaw nodes invoke \
  --node "iOS Node" \
  --command canvas.navigate \
  --params '{"url":"http://<gateway-host>:18793/__openclaw__/canvas/"}'

• Gateway canvas host provides:
  • /__openclaw__/canvas/
  • /__openclaw__/a2ui/
  
  
• iOS node auto-navigates to A2UI when advertised

Return to built-in scaffold:

 {"url":""}

Canvas Eval and Snapshot

Execute JavaScript

openclaw nodes invoke \
 --node "iOS Node" \
 --command canvas.eval \
 --params '{"javaScript":"(() => { const {ctx} = window.__openclaw; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'

Take Snapshot

openclaw nodes invoke \
  --node "iOS Node" \
  --command canvas.snapshot \
  --params '{"maxWidth":900,"format":"jpeg"}'

‍Voice Wake and Talk Mode

• Available through iOS app Settings
• iOS may suspend background audio
• Treat voice features as best-effort
• Most reliable when the app is in the foreground

Common Errors and Fixes

• NODE_BACKGROUND_UNAVAILABLE
  
  • Bring the iOS app to the foreground
  • Canvas, camera, and screen commands require it
• A2UI_HOST_NOT_CONFIGURED
  
  • Gateway did not advertise a canvas host
  • Verify canvasHost in the Gateway configuration
• Pairing prompt never appears

Run:

openclaw nodes pending

Approve manually with:

openclaw nodes approve <requestId>

• Reconnect fails after reinstall
  
  
  • Pairing token was removed from Keychain
  • Re-pair the iOS node

Conclusion

Running OpenClaw across platforms shows just how powerful agentic systems can be, but also how much responsibility they place on the user. Whether it’s cloud deployments, desktop environments, or mobile companion nodes, OpenClaw requires careful configuration, ongoing monitoring, and a strong security posture to avoid missteps.

That’s why many teams now look for an OpenClaw alternative that delivers similar automation benefits without exposing their systems to unnecessary risk. Multiple industry reports and independent analyses continue to highlight OpenClaw security issues, ranging from misconfigurations to overbroad system access. These concerns make OpenClaw better suited to advanced users who are comfortable managing their own infrastructure and security.

Knolli stands out as a powerful OpenClaw alternative built with security and operational control at its core. Instead of unrestricted system access, Knolli focuses on structured workflows, scoped permissions, and predictable outputs, making it a more secure choice for teams that want dependable AI copilots without the operational overhead.

If your goal is to move fast and stay secure, choosing a platform designed with guardrails from day one can make all the difference.