OpenClaw Connection Guide

This page focuses on one thing: the two most practical ways to connect to OpenClaw.

• LAN connection
• Tailscale remote connection

Both methods are centered around the gateway section in ~/.openclaw/openclaw.json, especially the initial connection token (gateway.auth.token).

Key Fields First (Applies to Both Methods)

{
  "gateway": {
    "mode": "local",
    "bind": "lan",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "replace with your own long token"
    },
    "tailscale": {
      "mode": "off"
    }
  }
}

Field notes:

• gateway.mode How the node runs Gateway. For most self-hosted cases, keep local.
• gateway.bind Listening scope. loopback is local-only; lan allows other devices in the same network.
• gateway.port Gateway port. Common default is 18789; clients must use the same port.
• gateway.auth.mode Auth mode. token is recommended.
• gateway.auth.token The token clients must provide for initial connection (critical).
• gateway.tailscale.mode OpenClaw's built-in Tailscale integration mode. In this guide we keep it off for simpler operations.

1. LAN Connection

Use this when your phone/computer and OpenClaw host are in the same LAN (same Wi-Fi or same subnet).

1) Recommended Gateway config

{
  "gateway": {
    "mode": "local",
    "bind": "lan",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your connection token"
    },
    "tailscale": {
      "mode": "off"
    }
  }
}

Key points:

• Use bind = lan, otherwise mobile devices cannot access Gateway from LAN.
• Keep auth.mode = token; do not switch to none.
• Keep tailscale.mode = off; LAN mode does not require it.

2) Get the initial token (gateway.auth.token)

Read directly from config:

jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json

If jq is not installed, open the file directly:

cat ~/.openclaw/openclaw.json

Then locate:

"gateway": {
  "auth": {
    "mode": "token",
    "token": "this is your initial connection token"
  }
}

After config changes, restart Gateway:

openclaw gateway restart

3) Let OpenClaw modify config from Control UI (Optional)

In your deployed OpenClaw Control UI, you can send this prompt directly to your own OpenClaw so it updates ~/.openclaw/openclaw.json for LAN mode:

Please modify the gateway section in ~/.openclaw/openclaw.json with these requirements:
1) Set gateway.mode to "local"
2) Set gateway.bind to "lan"
3) Set gateway.port to 18789 (if this port is occupied, keep a valid available port and tell me)
4) Set gateway.auth.mode to "token"
5) Set gateway.tailscale.mode to "off"
6) Keep existing gateway.auth.token; if missing, generate a strong token and write it to gateway.auth.token
7) Validate JSON format after changes and print the final gateway config snippet
8) Print token retrieval command: jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json
9) Do NOT restart Gateway; only remind me to restart manually

Important: Gateway restart must still be done manually.

• Terminal command: openclaw gateway restart
• Cloud-hosted deployment: restart the server or corresponding service
• Docker deployment: restart containers (docker restart <container> or docker compose restart)

4) Client connection

1. In ClawPilot or another OpenClaw client, enter host LAN IP and gateway.port.
2. Choose token as auth method.
3. Paste gateway.auth.token to complete connection.

2. Tailscale Remote Connection

Tailscale is a secure device-networking tool that lets you access your home/office host from outside networks. Register: tailscale.com/start Install: tailscale.com/download

1) Recommended Gateway config (critical)

Keep it the same as LAN setup and do not enable OpenClaw built-in Tailscale mode:

{
  "gateway": {
    "mode": "local",
    "bind": "lan",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your connection token"
    },
    "tailscale": {
      "mode": "off"
    }
  }
}

Why this is simpler:

• gateway.tailscale.mode = off avoids extra mode complexity.
• Continue using gateway.auth.token as your primary auth method.
• LAN and remote setup share the same auth logic, reducing troubleshooting cost.

2) Remote connection steps

1. Install Tailscale on OpenClaw host and your phone/computer, then sign into the same account.
2. On the host, get Tailscale IPv4:

tailscale ip -4

3. Get OpenClaw initial token:

jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json

4. In ClawPilot or another OpenClaw client, enter <tailscale-ip>:<gateway.port>, choose token auth, and paste token.

3) Let OpenClaw modify config from Control UI (Optional)

In your deployed OpenClaw Control UI, you can send this prompt so OpenClaw applies the minimal remote-ready config:

Please modify the gateway section in ~/.openclaw/openclaw.json for a minimal Tailscale remote setup with these requirements:
1) Set gateway.mode to "local"
2) Set gateway.bind to "lan"
3) Set gateway.port to 18789 (if this port is occupied, keep a valid available port and tell me)
4) Set gateway.auth.mode to "token"
5) Set gateway.tailscale.mode to "off"
6) Keep existing gateway.auth.token; if missing, generate a strong token and write it to gateway.auth.token
7) Validate JSON format after changes and print the final gateway config snippet
8) Print token retrieval command: jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json
9) Do NOT restart Gateway; only remind me to restart manually

Important: Gateway restart must still be done manually.

• Terminal command: openclaw gateway restart
• Cloud-hosted deployment: restart the server or corresponding service
• Docker deployment: restart containers (docker restart <container> or docker compose restart)

4) Minimal troubleshooting order

1. openclaw gateway status
2. tailscale status
3. Confirm client port matches gateway.port
4. Confirm token exactly matches gateway.auth.token

References

• OpenClaw Gateway Configuration
• OpenClaw Configuration Reference
• Tailscale Start
• OpenClaw Tailscale
• OpenClaw Security