--- name: openclaw-tailscale-remote-access description: "Configure or repair OpenClaw remote access over Tailscale with a directly executable workflow: inspect state, apply the gateway config, enable Tailscale Serve over HTTPS, validate browser access, and handle origin, DNS, or pairing failures." metadata: openclaw: version: "1.0.1" homepage: "https://github.com/JiangAgentLabs/openclaw-tailscale-remote-access" requires: bins: - "bash" - "python3" - "tailscale" - "systemctl" - "curl" configs: - "~/.openclaw/openclaw.json" --- # 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 `127.0.0.1` - Browser access goes through `https://..ts.net` - `auth.mode` is `token` - `auth.allowTailscale` is `true` ## 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: `..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`: ```bash export SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/openclaw-tailscale-remote-access" if [ ! -d "$SKILL_DIR" ] && [ -d "$HOME/Downloads/openclaw-tailscale-remote-access" ]; then export SKILL_DIR="$HOME/Downloads/openclaw-tailscale-remote-access" fi export OPENCLAW_CONFIG="${OPENCLAW_CONFIG:-$HOME/.openclaw/openclaw.json}" export GATEWAY_PORT="${GATEWAY_PORT:-18789}" export TS_HOSTNAME="..ts.net" export GATEWAY_TOKEN="" ``` ## Safety Rules 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: ```bash bash "$SKILL_DIR/scripts/inspect_remote_access.sh" "$OPENCLAW_CONFIG" ``` 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: ```bash printf 'SSH_CONNECTION=%s\n' "${SSH_CONNECTION:-}" hostname tailscale ip -4 2>/dev/null || true ``` 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: ```bash python3 "$SKILL_DIR/scripts/apply_gateway_config.py" \ --config "$OPENCLAW_CONFIG" \ --ts-hostname "$TS_HOSTNAME" \ --token "$GATEWAY_TOKEN" \ --port "$GATEWAY_PORT" ``` The script enforces this shape: ```json { "gateway": { "port": 18789, "mode": "local", "bind": "loopback", "controlUi": { "allowedOrigins": [ "http://localhost:18789", "http://127.0.0.1:18789", "https://..ts.net" ] }, "auth": { "mode": "token", "token": "", "allowTailscale": true }, "tailscale": { "mode": "serve", "resetOnExit": false } } } ``` ### 4. Restart The Gateway ```bash systemctl --user restart openclaw-gateway systemctl --user status openclaw-gateway --no-pager ``` 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: ```bash tailscale up --accept-dns=false --accept-routes=false --ssh=false ``` 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: ```bash bash "$SKILL_DIR/scripts/configure_tailscale_serve.sh" --port "$GATEWAY_PORT" ``` If the node already has Serve config that must be replaced, rerun with: ```bash bash "$SKILL_DIR/scripts/configure_tailscale_serve.sh" --reset-first --port "$GATEWAY_PORT" ``` Expected mapping: ```text https://..ts.net/ -> http://127.0.0.1:18789/ ``` ### 7. Validate End To End Run these checks in order: ```bash tailscale status --json tailscale serve status --json systemctl --user status openclaw-gateway --no-pager tailscale ip -4 curl -vkI --resolve "$TS_HOSTNAME:443:$(tailscale ip -4 | head -n1)" "https://$TS_HOSTNAME/" ``` Expected results: - Tailscale backend is `Running` - Serve reports an HTTPS handler on TCP 443 - `openclaw-gateway` is `active (running)` - 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: ```bash tailscale set --accept-routes=false tailscale set --accept-dns=true scutil --dns | grep -E 'ts.net|tailscale' nslookup "$TS_HOSTNAME" ``` ## Pairing Required If the dashboard loads but reports `pairing required`: ```bash cat ~/.openclaw/devices/pending.json openclaw devices list openclaw devices approve ``` 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 - `origin not allowed` `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. - `pairing required` Approve the pending device on the gateway host. ## References - Read [remote-setup.md](./references/remote-setup.md) when you need the exact host-side setup sequence. - Read [troubleshooting.md](./references/troubleshooting.md) when configuration is already in place but access still fails.

OpenClaw Tailscale Remote Access

Description

Latest Changes

Install OpenClaw Tailscale Remote Access with One Click