How to Attach to a Remote OpenClaw Gateway over Tailscale and Prove the Intended Host Answered

Published May 12, 2026

A remote OpenClaw connection can be green for the wrong reason. A Tailscale node may answer a network probe while the Gateway is stopped. A port may belong to another process. A proxy may return a response from a different service.

The useful question is therefore two questions: can the client reach the expected Tailscale machine, and did the OpenClaw Gateway on that machine answer? This tutorial builds that evidence in layers. The commands are documentation-derived; no live infrastructure test is claimed here. The host-correlation procedure is a proposed operator test.

Start with the proof, not the endpoint

OpenClaw runs a Gateway process that owns the control connection, sessions, channels, and state. Its WebSocket listener uses loopback and port 18789 by default. The remote-access documentation describes Tailscale or another trusted private network as the direct path, with SSH tunnelling as a fallback.

Tailscale makes devices reachable, but it does not create the service on the destination. Its device-connection guide makes the separation explicit: identify the device, confirm that a service is running, then connect to that service.

That last limitation matters. This is an operator-grade proof record, not a cryptographic attestation scheme.

Choose the private Tailscale shape

OpenClaw documents two useful private patterns. Pick one before testing so that a successful response has a clear meaning.

Option A: Tailscale Serve for the Control UI

Serve keeps the Gateway on loopback and lets Tailscale provide an HTTPS URL for tailnet users. On the Gateway host, the documented command is:

openclaw gateway --tailscale serve

Open the resulting https://<MAGICDNS>/ address for the Control UI. Serve also carries the Gateway WebSocket surface. This is the cleaner choice when a browser or a private secure WebSocket endpoint is part of the workflow.

Serve is different from Funnel. Funnel is public internet exposure and is not needed for this question. Keep the first validation inside the tailnet.

Option B: bind the Gateway directly to the tailnet

For a native or command-line client, OpenClaw also documents a direct Tailnet bind:

{
  gateway: {
    bind: 'tailnet',
    auth: { mode: 'token', token: '<SERVER_TOKEN>' }
  }
}

The client then uses a private WebSocket such as ws://<TAILSCALE_IP>:18789. Replace the placeholder with a real secret through the supported secret mechanism or environment configuration. Do not commit a Gateway token to a repository or paste it into a diagnostic record.

A direct non-loopback bind still needs OpenClaw authentication. The client-side fields gateway.remote.token and gateway.remote.password tell a client how to authenticate; they do not configure server authentication by themselves. The OpenClaw Tailscale guide also distinguishes direct tailnet access from managed Serve and Funnel.

Prerequisites

• Tailscale is installed and logged in on the client and on the machine running the Gateway.
• The tailnet policy allows the client to reach the Gateway host and port. Tailscale now recommends grants, while ACLs remain supported.
• You know the Gateway port, authentication mode, and the OpenClaw documentation that matches the installed version.
• You can inspect the remote host through Tailscale SSH or an already-approved regular SSH path.
• The Gateway credential is available without exposing it in shell history, source control, screenshots, or logs.

If MagicDNS is enabled, use the machine name or its full tailnet name. The MagicDNS documentation notes that machine names are part of the generated DNS name and that a renamed machine receives a changed DNS entry. For a shared device, use its full domain name when required.

1. Record the intended Tailscale node

Start from the client. Save enough information to distinguish the chosen machine from a similarly named node:

tailscale status --json
tailscale ip <REMOTE_NAME>
tailscale whois --json <TAILSCALE_IP>

The Tailscale CLI reference documents the status table and its JSON form, the ip command, and whois. The status output includes a Tailscale IP, machine name, operating system, and connection state. The machine-readable form is useful for a run record, although its JSON format is subject to change.

whois is the more useful identity check for this task. Its response can include the machine name, node ID, Tailscale addresses, owner or tags, and capabilities. Compare the address in that response with the row selected in the Tailscale admin console. Record the node ID as well as the human-friendly name.

Do not treat a hostname match as enough. A machine name is an operator label. The node ID and the current Tailscale address make the mapping less ambiguous.

2. Prove the Tailscale path

Test the path to the exact address or MagicDNS name you just recorded:

tailscale ping --verbose <TAILSCALE_IP>

tailscale ping is a Tailscale-only diagnostic and reports more connection detail than an ordinary ping. A result may show a direct path or a relay. Either can be an expected transport outcome. The important result at this stage is that the intended Tailscale node answers.

If you selected the direct-bind layout, you can make a separate TCP check:

tailscale nc <TAILSCALE_IP> 18789

A successful port connection narrows the problem to the application layer. It does not prove that OpenClaw owns the port, so do not stop here.

If the node is absent from the inventory or tailscale ping fails, investigate tailnet membership, device state, DNS, and access policy first. Changing OpenClaw bind settings will not repair a missing Tailscale path.

3. Inspect the host that is supposed to run OpenClaw

Use Tailscale SSH when it is enabled and permitted by policy:

tailscale ssh <REMOTE_USER>@<MAGICDNS>

Tailscale documents that this command checks the destination SSH host key against the node key advertised through the Tailscale coordination system. Tailscale SSH itself needs a policy permitting the source, destination, and SSH user. On sandboxed macOS builds where the command is unavailable, use the regular SSH client over the verified Tailscale name or address.

Once on the host, record local evidence:

hostname
tailscale ip -4
openclaw gateway status
openclaw gateway status --json

The operating-system hostname and the Tailscale machine name may not be identical. That is not automatically a failure, but the mapping should be written down. The local Gateway status should show the Gateway process and its configured endpoint. If necessary, keep a second session open for:

openclaw logs --follow

The purpose of this step is correlation. You are checking that the machine reached through the Tailscale identity is also the machine where the expected OpenClaw Gateway is running.

4. Attach the client

For a direct Tailnet connection, configure the client with a remote target:

{
  gateway: {
    mode: 'remote',
    remote: {
      transport: 'direct',
      url: 'ws://<TAILSCALE_IP>:18789',
      token: '<CLIENT_TOKEN>'
    }
  }
}

Use password instead of token when the Gateway uses password authentication. For a Serve endpoint, use the secure URL supplied by the Serve setup and follow the current OpenClaw remote-client instructions for the WebSocket target.

For a one-off check, pass the endpoint and credential explicitly:

openclaw gateway probe \
  --url 'ws://<TAILSCALE_IP>:18789' \
  --token "$OPENCLAW_GATEWAY_TOKEN"

OpenClaw's remote-access documentation warns that an explicit --url does not reuse configuration or environment credentials automatically. Supplying the token or password explicitly avoids a misleading authentication failure. Keep the value out of the saved command record.

5. Use an OpenClaw check that proves more than liveness

For a direct HTTP health check, request the documented endpoint:

curl -fsS 'http://<TAILSCALE_IP>:18789/health'

The OpenClaw health documentation describes this endpoint as a fast liveness check. A healthy response contains an ok value of true and a live status. That is useful, but it only proves that the Gateway HTTP server is live.

Now run the authenticated WebSocket checks:

openclaw gateway probe \
  --url 'ws://<TAILSCALE_IP>:18789' \
  --token "$OPENCLAW_GATEWAY_TOKEN"

openclaw gateway status \
  --url 'ws://<TAILSCALE_IP>:18789' \
  --token "$OPENCLAW_GATEWAY_TOKEN" \
  --require-rpc

The current Gateway documentation describes openclaw gateway status --require-rpc as read-scope RPC proof rather than simple reachability. Its documented healthy baseline is a running runtime, an OK connectivity probe, and a capability line that matches what you expect. The Gateway command reference also documents a warning for multiple reachable Gateway identities.

If the client is already configured in remote mode, openclaw health --verbose --json is another useful read-only check. The verbose form forces a live probe. A successful health RPC means the Gateway produced its snapshot; it does not mean every channel queue is clear.

I would make this first proof read-only. A status request gives you a cleaner failure signal than sending a message, invoking an agent, editing a file, or calling a tool.

Build the evidence record

Keep the outputs together with one timestamp:

1. The Tailscale node name, node ID, and address from status and whois.
2. The tailscale ping result and whether the path was direct or relayed.
3. The remote host's hostname, tailscale ip -4, and Gateway status.
4. The exact OpenClaw URL, port, authentication mode, client version, and redacted probe result.
5. A matching host-side log observation when the Gateway log exposes one at the connection time.

If you use managed Serve and it reports a route conflict, inspect the route before changing it:

tailscale serve status --json

This identifies the active Serve session, hostname, path, and proxy target where available. It checks route ownership. It still does not replace the Gateway RPC proof.

This record lets you say something precise: the Tailscale node with this identity was reachable, the expected host showed the Gateway, and an authenticated OpenClaw RPC response arrived at the configured endpoint at the recorded time.

Failure paths

The node is missing or unreachable

Check that both devices are logged into the intended tailnet and that the access policy permits the connection. Tailscale access control applies to the network path; Tailscale SSH adds its own SSH-specific rules. Do not diagnose an OpenClaw listener until the node identity and path are working.

The path works but port 18789 does not

Check the Gateway port, bind mode, and host firewall. A loopback-only Gateway will not answer a direct Tailnet connection. Use Tailscale Serve with a loopback Gateway, or configure the documented direct Tailnet bind with Gateway authentication. If the service uses a non-default port, replace 18789 in every test.

/health works but the RPC probe fails

The HTTP server is alive, but the WebSocket path, URL, or credentials may be wrong. Recheck the exact endpoint and pass --token or --password when using --url. A token stored under the client remote configuration does not repair a missing server-side auth setting.

The browser works but an API call fails

Managed Tailscale identity headers have a narrow scope. OpenClaw documents them for Control UI WebSocket authentication and limited read-only avatar requests. Other HTTP API paths, including /v1/* and /tools/invoke, follow the Gateway's normal authentication mode. A working Control UI is not permission to assume that every API surface is authenticated the same way.

The probe reports multiple Gateway identities

Stop before performing a write. OpenClaw can warn when distinct Gateways answer or when it cannot prove that reachable targets are the same Gateway. Inspect tunnels, proxies, ports, profiles, and service managers. If multiple Gateways are intentional, give each one a unique port, configuration path, state directory, and workspace.

Security boundaries and rollback

Tailscale access and OpenClaw authentication are separate controls. The Tailscale access-control documentation describes grants and ACLs for deciding which sources can reach which destinations. OpenClaw requires its own Gateway auth for non-loopback binds. Keep those controls narrow and document who can operate the Gateway.

For Serve, OpenClaw can use Tailscale identity headers when gateway.auth.allowTailscale is enabled. The documentation says OpenClaw verifies the forwarded address through tailscale whois, but the flow assumes the Gateway host is trusted and does not replace normal auth for other HTTP APIs. If that host may run untrusted local code, use token or password authentication instead.

For a secure wss:// endpoint, OpenClaw supports gateway.remote.tlsFingerprint. For SSH transport, strict host-key verification is the default. Keep a saved fingerprint or host-key decision tied to the exact endpoint; a changed URL is not the same target.

To roll back a test, return the Gateway to loopback, disable the managed Tailscale mode if it is no longer needed, restart the Gateway, and rerun local status. If Serve ownership is unclear, inspect tailscale serve status --json before clearing any route. Do not widen the exposure just to make a failing test pass.

The final boundary is worth stating plainly: this process proves an operational chain, not a hostile-host-resistant identity claim. If the consequence of reaching the wrong machine is high, add stronger inventory, certificate, device-posture, and approval controls.

Sources

• Tailscale - OpenClaw - Serve, direct Tailnet bind, authentication modes, and identity-header scope. Accessed 2026-09-13.
• Remote access - OpenClaw - Remote WebSocket targets, explicit credentials, direct mode, TLS fingerprints, and SSH fallback. Accessed 2026-09-13.
• Health checks - OpenClaw - Health snapshots, live probes, JSON output, and the liveness endpoint. Accessed 2026-09-13.
• Gateway documentation in the OpenClaw repository - Status baseline, RPC proof, and multiple Gateway identity warnings. Accessed 2026-09-13.
• Tailscale CLI reference - Status, IP, ping, SSH, Serve status, and WhoIs commands. Accessed 2026-09-13.
• Connect to devices - Tailscale - Device identity, service reachability, and connection prerequisites. Accessed 2026-09-13.
• MagicDNS - Tailscale - Machine names, full tailnet names, and name-resolution behavior. Accessed 2026-09-13.
• Access control - Tailscale - Grants, ACLs, and Tailscale SSH authorization boundaries. Accessed 2026-09-13.