openclaw/docs/remote-management-ota.md

title, summary, read_when

title	summary	read_when
Remote Management and OTA Updates for Edge Devices	Practical guide for managing and updating OpenClaw on Pi, phones, and other always-on edge devices without physical access	Setting up a headless Pi or cheap-phone gateway Updating OpenClaw on an edge device remotely Automating OTA updates with version pinning Rolling back a broken update on a remote device

Remote Management and OTA Updates for Edge Devices

OpenClaw runs well on always-on edge devices: Raspberry Pi boards, cheap Android phones running Termux, low-power ARM servers, and VPS instances. This guide covers how to manage and update those devices without physically touching them.

1. Remote Access Setup

Tailscale (recommended)

Tailscale is the lowest-friction way to reach edge devices across NAT, firewalls, or carrier-grade networks.

Install and authenticate on the device:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

After authentication the device appears in your tailnet with a stable MagicDNS name (e.g., gateway-pi.tail1234.ts.net).

Expose the OpenClaw Control UI over Tailscale Serve:

// ~/.openclaw/openclaw.json
{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

Then restart the gateway:

openclaw gateway restart

Access the Control UI from any tailnet device at https://gateway-pi.tail1234.ts.net/.

If you prefer a direct Tailnet IP bind instead of Serve:

{
  gateway: {
    bind: "tailnet",
    auth: { mode: "token", token: "replace-with-your-token" },
  },
}

See Tailscale for full config options.

SSH Key Setup

Passwordless SSH is required for unattended remote operations (cron-based updates, automated health checks).

On the device, add your control machine's public key:

mkdir -p ~/.ssh
cat >> ~/.ssh/authorized_keys << 'EOF'
ssh-ed25519 AAAA... user@control-machine
EOF
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Test from your control machine:

ssh user@gateway-host 'openclaw --version'

Once SSH is working, you can also forward the gateway port for CLI use:

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
# Then from the control machine:
openclaw health
openclaw status --deep

SSH Hardening (edge devices)

On a headless Pi or phone, reduce the attack surface:

# /etc/ssh/sshd_config additions
PasswordAuthentication no
PermitRootLogin no
AllowUsers youruser

Restart sshd after editing: sudo systemctl restart sshd

---

2. OTA Update Strategy

Recommended: re-run the website installer

The safest update path for global npm installs is re-running the official installer. It upgrades in place and runs openclaw doctor automatically:

ssh user@gateway-host 'curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard'

For global npm installs (most edge deployments), the update is:

ssh user@gateway-host 'sudo npm i -g openclaw@latest && openclaw doctor --yes && openclaw gateway restart'

Notes:

• Global installs on most Linux systems require sudo because the binary lives under /usr/lib/node_modules.
• openclaw doctor --yes accepts default repair prompts non-interactively; it handles config migrations and supervisor config audits.
• openclaw gateway restart restarts the managed service (systemd user service on Linux).

Source installs (git checkout)

ssh user@gateway-host 'cd /path/to/openclaw && openclaw update --no-restart && openclaw doctor --yes && openclaw gateway restart'

openclaw update requires a clean worktree, runs git pull --rebase, installs deps, builds, and runs doctor. Use --no-restart to control the restart order yourself.

Manual equivalent (source install)

ssh user@gateway-host << 'EOF'
cd /path/to/openclaw
git pull --rebase origin main
pnpm install
pnpm build
openclaw doctor --yes
openclaw gateway restart
EOF

After every update: verify

ssh user@gateway-host << 'EOF'
openclaw --version
openclaw health
openclaw channels status --probe
EOF

---

3. Health Monitoring

Quick status check

ssh user@gateway-host 'openclaw status'

For a deeper probe (runs per-channel connectivity checks):

ssh user@gateway-host 'openclaw status --deep'

Gateway health endpoint

ssh user@gateway-host 'openclaw health --json'

Returns a full health snapshot including channel probe summaries, auth age, session-store summary, and probe duration. Exits non-zero if the gateway is unreachable or any probe fails.

Systemd service monitoring

On Linux, the gateway runs as a systemd user service:

# Service status
ssh user@gateway-host 'systemctl --user status openclaw-gateway'

# Tail live logs
ssh user@gateway-host 'journalctl --user -u openclaw-gateway -f'

# Last 50 lines
ssh user@gateway-host 'journalctl --user -u openclaw-gateway -n 50'

# Filter errors only
ssh user@gateway-host 'journalctl --user -u openclaw-gateway -p err --since "1 hour ago"'

Systemd user linger (gateway survives logout)

On a headless device, ensure the user service stays alive after SSH disconnects:

ssh user@gateway-host 'sudo loginctl enable-linger $USER'

openclaw doctor will also check this and offer to enable it.

Watchdog: simple cron health check

Add to the device's crontab (crontab -e on the device, or via the SSH heredoc below) to detect silent failures:

# Check gateway health every 15 minutes; restart if unhealthy
*/15 * * * * openclaw health || (openclaw gateway restart && echo "restarted $(date)" >> /tmp/openclaw-watchdog.log)

For a more robust watchdog with alerting (e.g., Telegram message on failure), see the Automation docs.

---

4. Rollback Procedure

Pin to a known-good version (global npm install)

If an update breaks something, install the last working version:

# Find the current version before updating (keep a note of it)
ssh user@gateway-host 'openclaw --version'

# Roll back to a specific version
ssh user@gateway-host 'sudo npm i -g [email protected] && openclaw doctor --yes && openclaw gateway restart'

To see all published versions:

npm view openclaw versions --json

Pin to a known-good git commit (source install)

ssh user@gateway-host << 'EOF'
cd /path/to/openclaw
# Find the last working commit
git log --oneline -20

# Check out a specific commit or date
git checkout "$(git rev-list -n 1 --before='2026-01-15' origin/main)"

# Or check out a specific tag
git checkout v2026.1.15

pnpm install
pnpm build
openclaw doctor --yes
openclaw gateway restart
EOF

To return to the latest after the issue is resolved:

git checkout main && git pull

Restore from config/state backup

If the update corrupted config or state, restore from a backup (see the backup strategy in the next section):

ssh user@gateway-host << 'EOF'
systemctl --user stop openclaw-gateway
cp -r ~/.openclaw.backup.20260115-120000/* ~/.openclaw/
chmod 600 ~/.openclaw/openclaw.json
systemctl --user start openclaw-gateway
EOF

---

5. Automating Updates Safely

Edge devices should update regularly but not silently break. The safest approach uses a version-pinned channel with a manual approval gate, falling back to full automation only when you are confident in the release channel.

Backup before every update

Create a timestamped backup of the OpenClaw state dir before updating:

# Add to crontab (runs at 2am daily)
0 2 * * * cp -r ~/.openclaw ~/.openclaw.backup.$(date +\%Y\%m\%d-\%H\%M\%S) && find ~/.openclaw.backup.* -maxdepth 0 -mtime +7 -exec rm -rf {} +

This keeps 7 days of backups and automatically removes old ones.

Automated weekly update (stable channel, global install)

Add to the device's crontab (runs every Sunday at 3am):

0 3 * * 0 /usr/bin/npm i -g openclaw@latest 2>&1 | tee /tmp/openclaw-update.log && /usr/local/bin/openclaw doctor --yes >> /tmp/openclaw-update.log 2>&1 && /usr/local/bin/openclaw gateway restart >> /tmp/openclaw-update.log 2>&1

Notes:

• Use absolute paths in cron (the PATH is minimal).
• openclaw@latest tracks the stable release channel only (tagged releases). This is the safest channel for unattended updates.
• Redirect stdout and stderr to a log file so you can review what happened: cat /tmp/openclaw-update.log.

Pin to a specific version (maximum stability)

If you want zero surprise updates, pin the version explicitly:

# Install once at a fixed version
sudo npm i -g [email protected]

# When you're ready to update, explicitly bump the pin
sudo npm i -g [email protected]

Then control updates manually or through a reviewed deploy script rather than automation.

Switch release channels

# Track beta (pre-releases)
ssh user@gateway-host 'openclaw update --channel beta'

# Switch back to stable
ssh user@gateway-host 'openclaw update --channel stable'

Channel semantics:

• stable: tagged releases (vYYYY.M.D), npm dist-tag latest — recommended for edge devices.
• beta: pre-release tags (vYYYY.M.D-beta.N) — get new features earlier, with more risk.
• dev: moving head on main — not recommended for unattended edge devices.

Staging: test on one device before rolling to all

If you have multiple edge devices, update one first and verify health before updating the rest:

# Update and verify device-1
ssh user@device-1 'sudo npm i -g openclaw@latest && openclaw doctor --yes && openclaw gateway restart'
ssh user@device-1 'openclaw health && openclaw channels status --probe'

# If healthy, roll out to the rest
for host in device-2 device-3; do
  ssh user@$host 'sudo npm i -g openclaw@latest && openclaw doctor --yes && openclaw gateway restart'
  ssh user@$host 'openclaw health'
done

---

6. Quick Reference

SSH one-liners

# Check version
ssh user@gateway-host 'openclaw --version'

# Health check
ssh user@gateway-host 'openclaw health --json'

# Full update (global install)
ssh user@gateway-host 'sudo npm i -g openclaw@latest && openclaw doctor --yes && openclaw gateway restart'

# Restart gateway only
ssh user@gateway-host 'openclaw gateway restart'

# Restart systemd service directly
ssh user@gateway-host 'systemctl --user restart openclaw-gateway'

# Read recent logs
ssh user@gateway-host 'journalctl --user -u openclaw-gateway -n 100'

# Check channels
ssh user@gateway-host 'openclaw channels status --probe'

# Roll back to a pinned version
ssh user@gateway-host 'sudo npm i -g openclaw@<version> && openclaw doctor --yes && openclaw gateway restart'

Cron template

# Backup state daily at 2am (7-day retention)
0 2 * * * cp -r ~/.openclaw ~/.openclaw.backup.$(date +\%Y\%m\%d) && find ~/.openclaw.backup.* -maxdepth 0 -mtime +7 -exec rm -rf {} +

# Health watchdog every 15 min — restart if unhealthy
*/15 * * * * /usr/local/bin/openclaw health || (/usr/local/bin/openclaw gateway restart && echo "restarted $(date)" >> /tmp/openclaw-watchdog.log)

# Weekly update on stable channel (Sunday 3am)
0 3 * * 0 /usr/bin/npm i -g openclaw@latest && /usr/local/bin/openclaw doctor --yes && /usr/local/bin/openclaw gateway restart

---

Related docs

• Updating — full update command reference
• Tailscale — Serve/Funnel config options
• Remote Access — SSH tunnels and remote CLI defaults
• Doctor — repair, migrate, and audit
• Health Checks — health and status commands
• Troubleshooting — common issues and fixes