Running OpenClaw Remotely: macOS to Remote Host

I often find myself wanting to keep my local machine clean while still getting the benefits of a native desktop app. Sometimes you need a process to stay alive on a server that doesn’t go to sleep when you close your laptop lid.

I’ve found that using an SSH-based remote flow makes the transition between a local environment and a remote host much easier. This setup allows your Mac to act as a full remote control for an OpenClaw gateway running elsewhere.

What You’ll Need

• Node and pnpm installed on your remote host.
• OpenClaw CLI built and linked globally (pnpm install && pnpm build && pnpm link --global).
• openclaw added to the remote PATH (e.g., in /usr/local/bin).
• SSH access configured with key authentication (Tailscale is recommended).

Quick Start

1. Prepare the remote host: Install the CLI and run openclaw channels login --verbose on that machine to scan the WhatsApp QR code.
2. Configure the app: Open Settings → General in the macOS app and select Remote over SSH under the “OpenClaw runs” section.
3. Set transport and target: Choose SSH tunnel or Direct (ws/wss) and enter your user@host in the SSH target field.
4. Verify: Click Test remote. If the app successfully runs openclaw status --json on your server, you are ready to go.

Remote Transports

You can choose between two ways to move data:

• SSH tunnel: This uses ssh -N -L to forward the gateway port to your localhost. The gateway will see the IP as 127.0.0.1.
• Direct (ws/wss): This connects straight to the gateway URL, which is useful if you are using a reverse proxy or Tailscale Serve.

Notification Sounds

You can trigger specific sounds for notifications using the CLI. There is no global default sound anymore; you choose one per request:

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

Troubleshooting

• exit 127 / not found: This means openclaw isn’t in the PATH for non-login shells. Add it to /etc/paths or symlink it into /usr/local/bin.
• Health probe failed: Check your SSH reachability and ensure the CLI is logged in by running openclaw status --json on the remote host.
• Web Chat stuck: Confirm the gateway is running and that the forwarded port matches the gateway WebSocket port.
• Node IP shows 127.0.0.1: This is expected when using the SSH tunnel. Switch to Direct (ws/wss) if you need the gateway to see your real client IP.

If you hit a wall with your configuration, you can ask the AI Setup Assistant for help.

What’s Next

• Security Settings
• Tailscale Integration