Onepilot

OpenClaw setup from iPhone — and how to keep it running

Most "OpenClaw not working" problems trace back to three things: Node.js too old, the gateway running as a foreground process, or Telegram privacy mode silently dropping group messages. This page is the evergreen deploy that avoids all three, driven from iPhone.

The five steps

  1. Add a Linux or macOS host. Hostname, port, SSH credentials. Credentials live in the iOS Keychain.
  2. Deploy OpenClaw via Onepilot's wizard. Onepilot installs nvm in the user's home directory, pins Node.js LTS (20+), and installs the OpenClaw CLI globally under that nvm. No sudo at any point.
  3. Register as a persistent service. Onepilot wires the gateway to systemd-user on Linux or launchd on macOS, so the gateway restarts on crash and survives reboots. This is the step manual installs most often skip.
  4. Wire a channel. Pick Telegram, Discord, or Slack. For Telegram groups, you must disable privacy mode via BotFather (/setprivacy → Disable) or the bot will silently ignore every message that does not @-mention it.
  5. Verify. Send a test message. The agent replies within seconds. Onepilot's gateway status indicator reads green; if it reads amber or red, tap for the last log line.

The three failure modes that account for most issues

1. Node.js too old

OpenClaw requires Node 20+. System Node at 16 or 18 will start the process and fail to load core modules without a clear error. Run node --version on the host. If under 20, install nvm and reinstall OpenClaw under it. Onepilot does this automatically.

2. Gateway running as a foreground process

If you started OpenClaw with npx openclaw in a terminal and closed the terminal, the gateway died with it. Use a process supervisor — systemd-user on Linux, launchd on macOS, or pm2 — so the gateway is always there. Onepilot wires this for you at deploy time.

3. Telegram privacy mode

Telegram bots default to privacy mode: they only see messages that explicitly @-mention them or start with /. Group messages without one of those are dropped before the bot ever sees them. Disable privacy mode in BotFather; the bot starts seeing everything within a minute.

Reset and reinstall

A full wipe is two commands: rm -rf ~/.nvm and rm -rf ~/.openclaw. Skill files and channel configs in ~/.openclaw are erased; the Telegram bot token survives because it lives with BotFather, not on your host. Re-run the Onepilot wizard to reinstall.

For a soft reset (keep skills, restart the process), Onepilot exposes a one-tap restart in the OpenClaw tab that runs systemctl --user restart openclaw (or the launchd equivalent) over the existing SSH session.

Related

FAQ

Why is my OpenClaw gateway not responding?

The most common cause in 2026 is a Node.js version mismatch — OpenClaw requires Node 20 or newer, and a system Node at 16 or 18 will silently start but fail to load core modules. Onepilot pins OpenClaw to an LTS Node via nvm in the user's home directory, which avoids this. If you installed OpenClaw outside Onepilot, run node --version on the host and reinstall under nvm if it returns less than 20.

How do I keep OpenClaw running after I close the SSH session?

OpenClaw must run as a persistent background process. Onepilot's deploy wizard registers it with systemd-user (or launchd on macOS) so it survives logouts, terminal closes, and host reboots. If you installed manually, use a process supervisor — systemd, launchd, or pm2 — not nohup, which detaches but doesn't restart on crash.

Why does my OpenClaw Telegram bot ignore messages in groups?

Telegram bots default to privacy mode, where they only receive messages that explicitly @-mention them or start with a slash command. To make the bot read all group messages, talk to BotFather, run /setprivacy, pick your bot, and choose Disable. The change takes effect within a minute. The bot still needs to be a group member.

What hardware can run OpenClaw?

OpenClaw is a Node.js server. It runs on any Linux or macOS host with Node 20+, at least 1 GB RAM, and 10 GB disk. Common 2026 setups: a Raspberry Pi 5 at home (8 GB, plenty of headroom), a Mac mini, a NAS running sshd, a small VPS. The host needs to stay on — that is the only real constraint.

How do I install OpenClaw without sudo?

Use nvm (Node Version Manager) installed in your user's home directory, then npm install -g openclaw with that nvm Node active. Onepilot does this automatically. The full install lives under ~/.nvm and ~/.openclaw — uninstall is rm -rf on those two directories. No system files are touched.

Can I run multiple OpenClaw gateways on one host?

Yes. Each gateway needs its own working directory and its own port. A common 2026 pattern is one gateway per identity — one for personal, one for work — each with its own Telegram bot and skill set. Onepilot supports multiple gateways on the same host through the deploy wizard; pick a different working directory and port at deploy time.

How do I reset OpenClaw if it gets stuck?

Stop the process (systemctl --user stop openclaw on Linux, launchctl unload on macOS), then either restart it cleanly with the inverse command, or wipe and redeploy. A full wipe is rm -rf ~/.nvm ~/.openclaw followed by re-running the Onepilot wizard. Skill files and channel configs in ~/.openclaw are erased; agent memory is gone. The Telegram bot token survives because it lives with BotFather, not on your host.

Deploy OpenClaw from your iPhone

Free to get started. Bring your own host and your own LLM key.

Join the waitlist