When your OpenClaw Gateway runs only on a Canada remote Mac mini M4 and teammates in APAC want iPhones, iPads, or Android devices to join as nodes (role: node), the question is not whether the mobile app installs — it is whether the phone’s WebSocket can reach a compliant wss:// endpoint on an always-on host, and whether operators align CLI approval with gateway.mode: "remote". This page is a gateway-owned node pairing runbook for 2026. For macOS menu-bar clients, Dashboard bookmarks, and 18789 over SSH/Tailnet, read OpenClaw 2026: Canada-only gateway on a remote Mac M4 — macOS clients over SSH & Tailnet, Dashboard, TCP 18789, trans-Pacific tokens, loopback, and LaunchAgent persistence — that article wires operators; this one wires phones. If the Gateway is not installed yet, complete OpenClaw 2026: Remote Mac install, deploy & troubleshooting — openclaw onboard, Gateway daemon, and Canada M4 resource planning first.
Why a Canada M4 should be the sole Gateway for mobile nodes
In OpenClaw’s remote model, each host should run one Gateway process unless you deliberately isolate profiles. The Gateway owns sessions, channels, auth, and agent state; iOS/Android apps do not host a Gateway — they connect as peripheral nodes over the Gateway WebSocket and exchange node.* RPC. A leased Mac mini M4 in Canada fits the “always online” role: laptops sleep, but Telegram/Slack channels and pairing queues should not. Phones supply camera, sensors, or field actions; the M4 supplies continuity.
The common failure mode for trans-Pacific teams is standing up a second Gateway on an APAC laptop, which splits tokens, lets pairing requests expire on the wrong host, and makes openclaw nodes pending look empty while the phone spins. The fix is one Canada Gateway + every CLI and node aimed at remote, with APAC staff managing the host over SSH or a tailnet rather than running another Gateway locally.
Gateway-owned pairing in 2026 (what changed)
Since the gateway-owned pairing model, the Gateway is the source of truth for which nodes may join. The flow is: node connects via WebSocket → Gateway stores a pending request and emits node.pair.requested → operator runs openclaw nodes approve <requestId> (or the equivalent UI) → Gateway issues a token → node reconnects as paired. Pending entries expire after five minutes; regenerate QR or setup codes instead of chasing stale requests.
From 2026.3.31 onward, node commands stay disabled until node pairing is approved — device pairing alone is not enough to expose declared node commands. Treat openclaw devices approve and openclaw nodes approve as related but distinct gates: phones may appear in device lists while node RPC still returns 1008: pairing required until the node store shows approved. If openclaw nodes pending stays empty after a scan, upgrade to a build that writes WebSocket pairing state into the node store (2026.2.28+ fixes are documented upstream) before opening a network ticket.
Protocol-wise, operators interact with node.pair.list, node.pair.approve, and node.pair.reject through the CLI wrappers above; UIs are thin clients on the same Gateway truth. That matters for audits: the Canada host’s pairing log is authoritative, not whichever laptop last opened the mobile app.
gateway.mode remote and credential priority
On the Canada host, the Gateway should listen on 127.0.0.1:18789 (confirm your build’s default; document one port for the team). On APAC operator laptops, set gateway.mode: "remote" so openclaw health, openclaw nodes pending, and approve commands hit Canada through SSH or Tailscale, not an empty local port.
Official remote guidance: when the Gateway is loopback-only, keep gateway.remote.url as ws://127.0.0.1:18789 and establish SSH local forwarding before CLI. For tailnet-direct access, use transport: "direct" with a private ws:// or wss:// URL. Critical rule: --url does not implicitly reuse the config token — pass --token or --password explicitly when overriding the URL.
{
gateway: {
mode: "remote",
remote: {
url: "ws://127.0.0.1:18789",
token: "<gateway-token>",
sshTarget: "ca-m4-gateway",
},
},
}
{
gateway: {
mode: "remote",
remote: {
transport: "direct",
url: "wss://ca-m4.your-tailnet.ts.net",
token: "<gateway-token>",
},
},
}
| Credential source | Precedence | Typical mistake |
|---|---|---|
CLI --token / --password |
Highest when provided | Assuming --url picks up config token |
OPENCLAW_GATEWAY_TOKEN env |
Overrides file for one shell | LaunchAgent not inheriting the same env as SSH |
gateway.remote.token in config |
Default for remote mode | Rotated on host but not on phones |
| macOS app “Remote” profile | Separate UI store | CLI green while app still has old token |
Pairing runbook: loopback green to nodes approve
Assume the Gateway is already managed by launchd on the Canada M4. Do not point phones at a public plaintext ws:// IP if any step below fails.
Step 1 — Loopback health on the Gateway host
SSH to the Canada Mac and verify listen + health:
curl -fsS "http://127.0.0.1:18789/health" && echo OK lsof -nP -iTCP:18789 -sTCP:LISTEN
Step 2 — Secure WebSocket entry for phones
For cross-network mobile pairing, iOS/Android fail-closed on plaintext ws://. Expose real TLS as wss://<magicdns> via Tailscale Serve (preferred while Gateway stays loopback-bound) or an enterprise reverse proxy with a trusted certificate chain. Office LAN debugging may use ws://; trans-Pacific phones on the public Internet may not.
Step 3 — QR / setup code and node pending
On the host (or on a laptop with an active tunnel):
openclaw qr openclaw qr --remote openclaw nodes pending openclaw nodes approve <requestId> openclaw nodes status
After the phone scans, confirm the pending row appears before approving. Bind approvals to ticket IDs in shared on-call docs so midnight contractors do not approve unknown fingerprints.
Step 4 — Smoke-test node RPC
Trigger a minimal node.* call from the Gateway side (or a channel workflow that needs node tools). High Pacific RTT alone is not failure; frequent disconnects point to tailnet path, MTU, or phone power-saving — not necessarily reinstalling the app.
Secure entry decision matrix (phones vs operators)
Phones lack SSH tunnels; operators often have them. Keep those paths separate in runbooks.
| Entry type | Phone protocol | Typical use | Risk |
|---|---|---|---|
LAN ws://192.168.x.x:18789 |
Plain ws (private LAN) | Office Wi‑Fi debug | Not for trans-Pacific public Internet |
Tailscale Serve wss://*.ts.net |
wss + tailnet identity | APAC phones + Canada Gateway | ACL reviews per hire; host must be trusted |
| Private CA / corporate proxy wss | wss + bearer token | Certificate pinning policies | iOS needs trusted CA or pin config |
Public IP ws:// |
Remote pairing rejected | — | Fail-closed by design; do not expose 18789 raw |
-L, tailnet bookmarks) lives in the Canada-only gateway SSH/Tailnet tutorial. This article covers phone node wss pairing and nodes approve — do not reuse the same acceptance order (“open Dashboard first”) for mobile pairing tickets.
Trans-Pacific SSH: approve nodes when phones cannot join the tailnet yet
Contractor phones that cannot enroll in Tailscale still need a wss:// endpoint (Serve or corporate proxy). SSH helps operators run approve on loopback after tunneling — it does not replace the phone’s TLS path.
ssh -N -L 18789:127.0.0.1:18789 user@ca-m4-host # New terminal: remote config points at ws://127.0.0.1:18789 openclaw health --token "<gateway-token>" openclaw nodes pending openclaw nodes approve <requestId>
For 24/7 tunnels, persist ssh -N in a LaunchAgent on the operator Mac (see remote docs) and store gateway.remote.token in config, not shell profiles. The Canada host keeps Gateway on loopback only.
| Role | Recommended path | Pairing commands | If it fails, check |
|---|---|---|---|
| Canada M4 (Gateway) | loopback + launchd | openclaw qr, nodes pending |
lsof -i :18789, Gateway logs |
| APAC operator Mac | SSH -L + remote mode |
nodes approve, doctor |
Tunnel alive? Token explicit? |
| iOS / Android | wss:// tailnet or Serve |
App scan, node online badge | Public ws misuse, cert trust |
M4 capacity: one Gateway, many phone nodes
A 24 GB / 512 GB Canada M4 comfortably hosts one Gateway plus several paired nodes if channels and workspace snapshots are bounded. Add 1 TB / 2 TB when log retention, channel media, and workspace exports compete for APFS headroom. A second leased M4 is justified when you need isolated Gateway profiles (prod vs staging nodes) rather than because three phones inherently overload one Apple Silicon host — phones share sessions and quotas, they do not “fight” for the Gateway process.
Tag each approved device in your CMDB; pairing without ownership data becomes un-auditable across time zones. For disk and parallel expansion math when channels grow, see OpenClaw 2026 Canada M4 production node disk, channels renewal & gateway how-to FAQ.
openclaw doctor ticket playbook
Treat openclaw doctor (and --lint / --deep when available) as the single snapshot in tickets: run on the Gateway host SSH session and again from a tunneled remote CLI; diff the output. Doctor green but phone still pending usually means no nodes approve or the phone targets the wrong wss host. Doctor auth errors mean token surfaces mixed local/remote fallback.
Suggested ticket fields
Attach: UTC timestamp, openclaw --version, Gateway health curl, redacted openclaw nodes pending / nodes status, phone error text (secure endpoint required?), and whether Serve vs SSH-only vs direct tailnet is in use. VNC is rarely needed unless debugging macOS TCC for camera node tools.
Symptom → action tree
A. Phone says secure endpoint required → configure wss:// (Tailscale Serve first); stop publishing plaintext ws on a public IP.
B. Pending empty but phone spins → expired QR, wrong Gateway host, or WebSocket pairing bug fixed in 2026.2.28+ (upgrade before deep debugging).
C. CLI connection refused → verify Canada loopback, then laptop lsof -i :18789 during SSH forward.
D. Approved then immediate drop → tailnet ACL, phone battery saver, Gateway OOM; capture version before restart.
openclaw doctor openclaw doctor --lint openclaw gateway status openclaw nodes pending openclaw nodes status curl -fsS "http://127.0.0.1:18789/health" || true
Use case: APAC on-call phone triggers Canada automation
A Singapore on-call engineer pairs an iPhone node to the Canada Gateway over wss://ca-m4.team.ts.net. A Slack slash command routed through OpenClaw channels requests a camera snapshot via node.* RPC; the Gateway orchestrates on the M4 while the phone supplies the sensor path. Latency is dominated by the Pacific leg, but the Gateway stays up when the engineer’s MacBook sleeps. Approvals are logged with ticket IDs; tokens rotate quarterly without re-posting secrets in chat.
This pattern only works when pairing, channels, and tailnet ACLs are owned by the same platform team. If channels already run on the Canada host but phones never completed nodes approve, operators see healthy Slack delivery yet every node tool fails with pairing errors — a common support pattern that doctor snapshots surface quickly when you attach both nodes status and channel health in one ticket.
FAQ
Can iOS or Android host the Gateway?
No. Mobile apps are nodes only. Keep Canada M4 as the canonical Gateway unless you deliberately run isolated profiles on another host.
Why is wss mandatory for remote phone pairing?
Cross-network mobile pairing fail-closes plaintext ws:// to protect credentials and device fingerprints. LAN and documented simulator exceptions are in upstream docs.
Does gateway.mode remote change the Gateway host itself?
remote is a client setting. The Canada Mac still runs a local Gateway. Do not point the M4’s own config at remote loopback to itself.
SSH tunnel only, no Tailscale on the phone?
Phones still need a reachable wss:// endpoint (usually Tailscale Serve or a corporate proxy). SSH serves operator CLI and approve; it does not substitute TLS for the handset.
openclaw qr vs openclaw qr --remote?
--remote encodes setup aimed at the remote Gateway URL — use on a tunneled or tailnet-reachable operator machine so the QR does not reference laptop loopback by mistake.
Do multiple phones “compete” for the Gateway?
They share one Gateway process and quotas; they do not spawn duplicate daemons. Label devices and keep an approval audit trail.
Pairing works but node tools time out?
Separate WebSocket alive from slow RPC. Check Gateway CPU, disk, and channel queues before reinstalling mobile apps.
Doctor green over SSH but the phone still fails?
Doctor may validate the tunnel path while the phone uses a different wss hostname or an expired QR. Align the phone’s wss URL with Serve config and re-run nodes pending after scan.