Remote access

This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a dedicated host (desktop/server) and connecting clients to it.

• For operators (you / the macOS app): SSH tunneling is the universal fallback.
• For nodes (iOS/Android and future devices): connect to the Gateway WebSocket (LAN/tailnet or SSH tunnel as needed).

The core idea

• The Gateway WebSocket binds to loopback on your configured port (defaults to 18789).
• For remote use, you forward that loopback port over SSH (or use a tailnet/VPN and tunnel less).

Common VPN and tailnet setups

Think of the Gateway host as where the agent lives. It owns sessions, auth profiles, channels, and state. Your laptop, desktop, and nodes connect to that host.

Always-on Gateway in your tailnet

Run the Gateway on a persistent host (VPS or home server) and reach it via Tailscale or SSH.

• Best UX: keep
  text

  Copy

  gateway.bind: "loopback"
  and use Tailscale Serve for the Control UI.
• Fallback: keep loopback plus SSH tunnel from any machine that needs access.
• Examples: exe.dev (easy VM) or Hetzner (production VPS).

Ideal when your laptop sleeps often but you want the agent always-on.

Home desktop runs the Gateway

The laptop does not run the agent. It connects remotely:

• Use the macOS app's Remote over SSH mode (Settings → General → OpenClaw runs).
• The app opens and manages the tunnel, so WebChat and health checks just work.

Runbook: macOS remote access.

Laptop runs the Gateway

Keep the Gateway local but expose it safely:

• SSH tunnel to the laptop from other machines, or
• Tailscale Serve the Control UI and keep the Gateway loopback-only.

Guides: Tailscale and Web overview.

Command flow (what runs where)

One gateway service owns state + channels. Nodes are peripherals.

Flow example (Telegram → node):

• Telegram message arrives at the Gateway.
• Gateway runs the agent and decides whether to call a node tool.
• Gateway calls the node over the Gateway WebSocket (
  text

  Copy

  node.*
  RPC).
• Node returns the result; Gateway replies back out to Telegram.

Notes:

• Nodes do not run the gateway service. Only one gateway should run per host unless you intentionally run isolated profiles (see Multiple gateways).
• macOS app “node mode” is just a node client over the Gateway WebSocket.

SSH tunnel (CLI + tools)

Create a local tunnel to the remote Gateway WS:

bash
Copy
ssh -N -L 18789:127.0.0.1:18789 user@host

With the tunnel up:

• text

  Copy

  openclaw health
  and
  text

  Copy

  openclaw status --deep
  now reach the remote gateway via
  text

  Copy

  ws://127.0.0.1:18789
  .
• text

  Copy

  openclaw gateway status
  ,
  text

  Copy

  openclaw gateway health
  ,
  text

  Copy

  openclaw gateway probe
  , and
  text

  Copy

  openclaw gateway call
  can also target the forwarded URL via
  text

  Copy

  --url
  when needed.

CLI remote defaults

You can persist a remote target so CLI commands use it by default:

json5
Copy
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}

When the gateway is loopback-only, keep the URL at

and open the SSH tunnel first. In the macOS app’s SSH tunnel transport, discovered gateway hostnames belong in ; remains the local tunnel URL.

Credential precedence

Gateway credential resolution follows one shared contract across call/probe/status paths and Discord exec-approval monitoring. Node-host uses the same base contract with one local-mode exception (it intentionally ignores

):

• Explicit credentials (
  text

  Copy

  --token
  ,
  text

  Copy

  --password
  , or tool
  text

  Copy

  gatewayToken
  ) always win on call paths that accept explicit auth.
• URL override safety:
  • CLI URL overrides (
    text

    Copy

    --url
    ) never reuse implicit config/env credentials.
  • Env URL overrides (
    text

    Copy

    OPENCLAW_GATEWAY_URL
    ) may use env credentials only (
    text

    Copy

    OPENCLAW_GATEWAY_TOKEN
    /
    text

    Copy

    OPENCLAW_GATEWAY_PASSWORD
    ).
• Local mode defaults:
  • token:
    text

    Copy

    OPENCLAW_GATEWAY_TOKEN
    ->
    text

    Copy

    gateway.auth.token
    ->
    text

    Copy

    gateway.remote.token
    (remote fallback applies only when local auth token input is unset)
  • password:
    text

    Copy

    OPENCLAW_GATEWAY_PASSWORD
    ->
    text

    Copy

    gateway.auth.password
    ->
    text

    Copy

    gateway.remote.password
    (remote fallback applies only when local auth password input is unset)
• Remote mode defaults:
  • token:
    text

    Copy

    gateway.remote.token
    ->
    text

    Copy

    OPENCLAW_GATEWAY_TOKEN
    ->
    text

    Copy

    gateway.auth.token
  • password:
    text

    Copy

    OPENCLAW_GATEWAY_PASSWORD
    ->
    text

    Copy

    gateway.remote.password
    ->
    text

    Copy

    gateway.auth.password
• Node-host local-mode exception:
  text

  Copy

  gateway.remote.token
  /
  text

  Copy

  gateway.remote.password
  are ignored.
• Remote probe/status token checks are strict by default: they use
  text

  Copy

  gateway.remote.token
  only (no local token fallback) when targeting remote mode.
• Gateway env overrides use
  text

  Copy

  OPENCLAW_GATEWAY_*
  only.

Chat UI over SSH

WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects directly to the Gateway WebSocket.

• Forward
  text

  Copy

  18789
  over SSH (see above), then connect clients to
  text

  Copy

  ws://127.0.0.1:18789
  .
• On macOS, prefer the app’s “Remote over SSH” mode, which manages the tunnel automatically.

macOS app Remote over SSH

The macOS menu bar app can drive the same setup end-to-end (remote status checks, WebChat, and Voice Wake forwarding).

Runbook: macOS remote access.

Security rules (remote/VPN)

Short version: keep the Gateway loopback-only unless you’re sure you need a bind.

• Loopback + SSH/Tailscale Serve is the safest default (no public exposure).
• Plaintext
  text

  Copy

  ws://
  is loopback-only by default. For trusted private networks, set
  text

  Copy

  OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1
  on the client process as break-glass. There is no
  text

  Copy

  openclaw.json
  equivalent; this must be process environment for the client making the WebSocket connection.
• Non-loopback binds (
  text

  Copy

  lan
  /
  text

  Copy

  tailnet
  /
  text

  Copy

  custom
  , or
  text

  Copy

  auto
  when loopback is unavailable) must use gateway auth: token, password, or an identity-aware reverse proxy with
  text

  Copy

  gateway.auth.mode: "trusted-proxy"
  .
• text

  Copy

  gateway.remote.token
  /
  text

  Copy

  .password
  are client credential sources. They do not configure server auth by themselves.
• Local call paths can use
  text

  Copy

  gateway.remote.*
  as fallback only when
  text

  Copy

  gateway.auth.*
  is unset.
• If
  text

  Copy

  gateway.auth.token
  /
  text

  Copy

  gateway.auth.password
  is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking).
• text

  Copy

  gateway.remote.tlsFingerprint
  pins the remote TLS cert when using
  text

  Copy

  wss://
  .
• Tailscale Serve can authenticate Control UI/WebSocket traffic via identity headers when
  text

  Copy

  gateway.auth.allowTailscale: true
  ; HTTP API endpoints do not use that Tailscale header auth and instead follow the gateway's normal HTTP auth mode. This tokenless flow assumes the gateway host is trusted. Set it to
  text

  Copy

  false
  if you want shared-secret auth everywhere.
• Trusted-proxy auth expects non-loopback identity-aware proxy setups by default. Same-host loopback reverse proxies require explicit
  text

  Copy

  gateway.auth.trustedProxy.allowLoopback = true
  .
• Treat browser control like operator access: tailnet-only + deliberate node pairing.

Deep dive: Security.

macOS: persistent SSH tunnel via LaunchAgent

For macOS clients connecting to a remote gateway, the easiest persistent setup uses an SSH

config entry plus a LaunchAgent to keep the tunnel alive across reboots and crashes.

Step 1: add SSH config

Edit

:

ssh
Copy
Host remote-gateway
    HostName <REMOTE_IP>
    User <REMOTE_USER>
    LocalForward 18789 127.0.0.1:18789
    IdentityFile ~/.ssh/id_rsa

Replace

and with your values.

Step 2: copy SSH key (one-time)

bash
Copy
ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>

Step 3: configure the gateway token

Store the token in config so it persists across restarts:

bash
Copy
openclaw config set gateway.remote.token "<your-token>"

Step 4: create the LaunchAgent

Save this as

:

xml
Copy
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.openclaw.ssh-tunnel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/ssh</string>
        <string>-N</string>
        <string>remote-gateway</string>
    </array>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Step 5: load the LaunchAgent

bash
Copy
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist

The tunnel will start automatically at login, restart on crash, and keep the forwarded port live.

Troubleshooting

Check if the tunnel is running:

bash
Copy
ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

Restart the tunnel:

bash
Copy
launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

Stop the tunnel:

bash
Copy
launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel

Related

• Tailscale
• Authentication
• Remote gateway setup