OpenClaw Tailscale Remote Access

Use this skill when Codex needs to make an OpenClaw gateway reachable over Tailscale and the result must be directly configurable, not just described.

Prefer Tailscale Serve + HTTPS for browser access. The recommended shape is:

• - OpenClaw binds to INLINECODE1
• Browser access goes through INLINECODE2
• INLINECODE3 is INLINECODE4
• INLINECODE5 is INLINECODE6

Required Inputs

Collect these values before making changes:

• - a non-Tailscale access path to the Linux host

cloud console or public SSH is preferred

• - the OpenClaw config file path

default: ~/.openclaw/openclaw.json

• - the final MagicDNS hostname

example: <machine>.<tailnet>.ts.net

• - the gateway token to place in the config

Skill Resources

Resolve the skill directory first so Codex can call the bundled scripts even if the skill is still in ~/Downloads:

CODEBLOCK0

Safety Rules

1. 1. Do not run tailscale up from a Tailscale SSH session.
2. If you need to change Tailscale state, prefer a cloud console or public SSH session.
3. Do not switch OpenClaw to bind: "tailnet" unless the user explicitly accepts HTTP-only access and weaker browser behavior.
4. On a Mac client, keep Tailscale DNS enabled if the browser must resolve *.ts.net.

Direct Workflow

1. Inspect Current State

Run the bundled inspector first:

CODEBLOCK1

Use the output to answer these questions before changing anything:

• - is openclaw-gateway running
• is Tailscale running
• is an HTTPS Serve handler already present
• are there pending pairing requests

2. Confirm the Session Is Safe For tailscale up

Use these checks:

CODEBLOCK2

If the current shell is reached through Tailscale SSH or through a Tailscale IP, stop and switch to cloud console or public SSH before changing Tailscale state.

3. Apply the OpenClaw Gateway Config

The bundled script creates a timestamped backup and updates only the gateway fields needed for remote access:

CODEBLOCK3

The script enforces this shape:

CODEBLOCK4

4. Restart The Gateway

CODEBLOCK5

If the service does not return to active (running), fix that before touching Tailscale Serve.

5. Start Or Repair Tailscale In Low-Impact Mode

Use this only from a safe session:

CODEBLOCK6

If Tailscale says all non-default flags must be restated, rerun tailscale up with the existing non-default flags plus the flags above. Do not use --reset blindly.

6. Configure HTTPS Serve

Use the bundled helper:

CODEBLOCK7

If the node already has Serve config that must be replaced, rerun with:

CODEBLOCK8

Expected mapping:

CODEBLOCK9

7. Validate End To End

Run these checks in order:

CODEBLOCK10

Expected results:

• - Tailscale backend is INLINECODE18
• Serve reports an HTTPS handler on TCP 443
• INLINECODE19 is INLINECODE20
• the HTTPS request reaches the service and does not fail at DNS or TLS handshake

Client Repair

If the browser client is a Mac and *.ts.net stopped resolving after Tailscale changes, do not change the server bind mode. Repair the client first:

CODEBLOCK11

Pairing Required

If the dashboard loads but reports pairing required:

CODEBLOCK12

If the CLI path is broken, inspect the installed OpenClaw CLI or Python package on the host and call its built-in approval path. Do not manually edit pending.json or paired.json unless the user explicitly asks for a last-resort recovery.

Troubleshooting Priorities

• - INLINECODE25

controlUi.allowedOrigins is wrong; re-run the config script with the correct TS_HOSTNAME.

• - ERR_SSL_PROTOCOL_ERROR, invalid response, or TLS handshake failure

Check tailscale serve status, then inspect host DNS and certificate issuance.

• - NXDOMAIN for *.ts.net on the client

Fix client MagicDNS; do not switch the server to bind: "tailnet" just to bypass DNS.

• - INLINECODE34

Approve the pending device on the gateway host.

References

• - Read remote-setup.md when you need the exact host-side setup sequence.
• Read troubleshooting.md when configuration is already in place but access still fails.