2026 OpenClaw on headless Linux VPS: from install.sh to first channel reply using gateway probe and channels probe
Bare Ubuntu or Debian servers without a desktop reward disciplined acceptance tests. Prove Node, prove CLI path, prove RPC with gateway probe, prove transports with channels probe, then tune models. This article maps ufw and cloud security group thinking, links the official troubleshooting ladder, and contrasts bare VPS work with Docker, WSL2, systemd HOME drift, and hosted remote Mac baselines.
Contents
1. Headless Linux false positives that look like success
Headless Ubuntu or Debian VPS installs for OpenClaw fail quietly when teams celebrate the installer exit code instead of proving that the gateway can complete an RPC probe and that a real chat transport answers.
This runbook anchors the milestone on the first reliable channel reply, not on screenshots of the installer banner.
It follows the official troubleshooting ladder documented alongside gateway probe guidance, and it complements the Linux systemd HOME drift article, the Docker token matrix, the WSL2 cross-platform guide, and the macOS launchd restart note without duplicating their mechanisms.
Pain one is treating install success as production readiness.
The install script can place binaries while Node remains below the supported major, while PATH still points at an older global prefix, or while the interactive SSH user differs from the service user that will eventually run the gateway.
Run node version checks and which openclaw immediately after install, then capture openclaw status before editing JSON so the ticket shows which identity actually owns the config tree.
Pain two is opening inbound security groups while forgetting outbound DNS and TLS.
Chat providers need stable egress; default deny egress policies in some regulated VPCs surface as channel timeouts that resemble model throttling.
Follow the 20260506 ladder article before touching model strings so you do not chase Anthropic rate limits when transport never came online.
Pain three is confusing LISTEN with public reachability.
ss may show a listener bound only to loopback while the cloud console still blocks the port, or while ufw on the instance contradicts the security group.
Document both planes in the same change record so reviewers see the intersection, not whichever screen was convenient during the incident.
- Freeze parallel installers and editors against the same JSON.
- Tar snapshot home config trees before first merge.
- Print the ladder order in the ticket header for handoffs.
2. Plane selection matrix for related runbooks
Use the matrix to route readers to the correct companion article instead of mixing commands across planes.
| Plane | You own | First acceptance focus | Companion link |
|---|---|---|---|
| Bare VPS | Kernel, ufw, cloud SG, system Node | Listener, egress, probes | This article |
| Docker | Image digest, compose env | Bridge, websocket | Compose token matrix |
| WSL2 | systemd unit inside WSL, localhost | Port forward path | WSL2 guide |
| Remote Mac hosting | Vendor SLA, isolation | Always on baseline | SFTPMAC plans |
3. Eight step ladder from install.sh to first reply
Pain four is skipping gateway probe and jumping to gateway install force.
Forced reinstalls multiply processes and ports when the original issue was a firewall rule or a stale token file path.
Reserve force install for semver skew that the split brain article already justifies, after snapshots exist.
Pain five is blaming models when channels never probed green.
Run channels status probe after gateway status stabilizes, then inspect credentials directories, then inspect provider quotas.
Keep websocket close codes and HTTP status lines in the ticket so vendor support can replay your path.
Pain six is mixing bare VPS debugging advice with compose advice.
Compose uses bridge networks and injected env files; bare metal uses sshd, ufw, and possibly systemd user linger.
node -v
which openclaw
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw status
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe- Freeze concurrent edits across humans and CI.
- Export environment dumps for login shell, automation shell, and future service user.
- Verify Node twenty two plus and reinstall from approved packages if needed.
- Run install script and capture logs with rotation.
- Run status then gateway probe before any JSON surgery.
- Run gateway status and doctor, then repeat status after fixes.
- Adjust ufw and cloud rules inside a time boxed window with rollback notes.
- Probe channels then send one synthetic message per provider with screenshots.
4. Pass fail checklist for on call binders
Label tickets with the plane so the next engineer does not paste drop in fragments into a compose stack.
The decision matrix below is for choosing which existing SFTPMAC article to read first, not for picking a vendor.
Bare VPS operators own kernel cadence, openssh hardening, package mirrors, and Node upgrades.
Docker operators own image digests and token alignment.
| Layer | Signal | Pass criteria |
|---|---|---|
| Listener | ss and cloud UI | Intended bind address and exposure |
| RPC | gateway probe | Connectivity ok per team definition |
| Config | doctor | No blocking findings |
| Channels | channels status probe | Transport works end to end |
| Models | logs and models status | No sustained four twenty nine storms |
5. Firewalls, dual stack, and webhooks
Treat management plane, gateway RPC, and channel webhooks as three paths with explicit source, destination, and protocol. Time box temporary wide rules and roll back to least privilege after the first successful reply.
ufw and cloud security groups intersect: one allow plus one deny still yields deny. Paste both screenshots into the same ticket.
Dual stack teams validate AAAA records and listener families together to avoid Happy Eyeballs flakiness mistaken for application bugs.
Document whether TLS terminates on nginx or on the gateway because probe commands and health checks differ.
6. Five repeatable drills that harden first boot acceptance
Drill one snapshots the entire home tree and config fragments before any manual JSON edit, then verifies tarball size is non zero and checksum is recorded in the ticket so later responders trust the archive.
Drill two runs gateway probe from the same user identity that will own the long running process, proving that non interactive shells inherit the PATH you expect instead of the narrow PATH that cron inherited last week.
Drill three exercises outbound TLS to the chat provider endpoints from curl with verbose mode, capturing TLS handshake timing so you can distinguish DNS failure from middlebox interception from simple rate limiting.
Drill four toggles ufw rules in pairs, documenting each rule with a UTC timestamp and a rollback one liner so wide temporary openings never become silent permanent holes.
Drill five replays the synthetic channel message after each minor OpenClaw bump, storing only redacted screenshots while keeping raw logs in secured storage for compliance aware teams.
Together these drills shrink mean time to innocence when leadership asks whether the outage is the model vendor or your own perimeter, because you already hold ordered evidence from listener through transport layers.
They also reduce duplicate work across regions when multiple engineers follow the same printed binder instead of improvising slightly different sequences that never compare apples to apples during postmortems.
When drills surface repeated friction, that is the signal to revisit hosting strategy rather than layering more bespoke scripts on top of brittle snowflake servers.
7. Boundaries with split brain, Docker, macOS, and Linux HOME drift
Read the official ladder in gateway probe runbook before changing models. Use Linux systemd HOME drift after upgrades, not for first boot acceptance.
Add one more guardrail: keep a dated text file on the host listing the exact probe commands you ran, their exit codes, and the engineer initials, because headless rebuilds without that artifact routinely waste a full day rediscovering the same network intersection.
When you later automate the same host with Ansible or Terraform, translate that text file into idempotent tasks so future rebuilds inherit the ladder instead of rediscovering drift each quarter.
Treat those automation modules as living documentation that must stay in sync with upstream OpenClaw release notes whenever default ports or probe flags evolve.
Evidence discipline belongs in the same section as boundaries because auditors rarely care which heading you used; they care whether the ticket proves each hop. Capture the first screen of every probe output, not only the trailing ok line, and paste the resolved absolute path to the Node binary that systemd will execute, because upgrades that shuffle /usr/bin versus /usr/local/bin masquerade as mysterious gateway failures until someone compares the two shells side by side.
When your cloud provider exposes flow logs, attach excerpts that show SYN, RST, or idle timeout directionality for the management session and for the webhook path separately, since jump hosts with ProxyJump can make localhost based checks succeed while the production listener still sits behind the wrong security group. If you operate dual stack networks, note explicitly which chat providers still require IPv4 only egress so Happy Eyeballs retries do not get misfiled under model instability.
Disaster recovery rehearsals should replay the ladder from a cold snapshot or freshly provisioned disk, not from a warm developer shell that already exported convenience aliases, and quarterly calendar reminders should trigger a lightweight outbound sweep after upstream certificate rotations even when application code did not change, because transparent proxies occasionally refresh trust stores without fanfare.
Pair a green gateway probe with a synthetic fetch against any object storage or artifact host your workflow depends on, because TLS success to a chat provider does not automatically prove presigned URL paths or regional S3 compatible endpoints behave the same after a firewall tweak. When fail2ban or similar tools run on the same instance, correlate ban windows with CI runner address ranges so automation retries are not silently starved while interactive engineers still see green checks.
8. FAQ
Q Install succeeds but gateway probe fails first? A Check listener bind, ufw, outbound DNS, and cloud rules before touching model strings.
Q Need a systemd user service immediately? A Foreground the gateway for acceptance, then daemonize with snapshots.
Q After rotating API keys or OAuth clients? A Rerun the full ladder once; yesterday’s green transport does not guarantee the same credential path tomorrow.
9. Conclusion and hosted remote Mac trade space
Ordered acceptance reduces weekend burn on headless Linux while keeping you honest about which layer failed.
Self hosted VPS stays powerful but demands ongoing kernel, distribution, and policy attention as teams scale.
Rotate webhook secrets the same way you rotate database passwords, with dual write windows and rollback notes, and keep one paragraph in every major ticket that names the next command in the ladder so a newcomer without shell access can still follow the evidence trail. Tag tickets dev, staging, and production with explicit colors so a firewall diff never lands on the wrong VPC during a late night merge.
When always on gateways and Apple aligned paths matter more than owning every kernel knob, compare engineering hours against SFTPMAC hosted remote Mac plans and help center runbooks.