Remote access

Remote access 문서는 OpenClaw 공식 문서(gateway/remote)를 한국어로 정리한 가이드입니다. Remote access using Gateway WS, SSH tunnels, and tailnets 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Remote access using Gateway WS, SSH tunnels, and tailnets

한국어 가이드 범위: gateway/remote 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

The core idea
Topology options
Command flow (what runs where)
SSH tunnel (CLI + tools)
CLI remote defaults
Credential precedence
Chat UI remote access
macOS app remote mode
Security rules (remote/VPN)
macOS: persistent SSH tunnel via LaunchAgent
Check if the tunnel is running
Restart the tunnel
Stop the tunnel
관련 문서

상세 내용

본문

OpenClaw runs one Gateway (the master) on a host and connects every client to it. The Gateway owns sessions, auth profiles, channels, and state; everything else is a client.

주요 항목:

Operators (you, or the macOS app): direct LAN/Tailnet WebSocket is simplest when the Gateway is reachable; SSH tunneling is the universal fallback.
Nodes (iOS/Android and other devices): connect to the Gateway WebSocket (LAN/tailnet or SSH tunnel).

The core idea

The Gateway WebSocket binds to loopback by default, on port 18789 (gateway.port). For remote use, either expose it through Tailscale Serve / a trusted LAN-Tailnet bind, or forward the loopback port over SSH.

Topology options

For the always-on and laptop setups, prefer keeping gateway.bind: "loopback" and using Tailscale Serve for the Control UI, or a trusted LAN/Tailnet bind with gateway.remote.transport: "direct". SSH tunnel is the fallback that works from any machine.

Setup	Where the Gateway runs	Best for
Always-on Gateway in your tailnet	Persistent host (VPS or home server), reached via Tailscale or SSH	Laptops that sleep often but need the agent always-on. See exe.dev (easy VM) or Hetzner (production VPS).
Home desktop	Desktop; laptop connects remotely via the macOS app's remote mode (Settings → Connection → OpenClaw runs)	Keeping the agent on hardware that stays powered on. Runbook: macOS remote access.
Laptop	Laptop, exposed safely via SSH tunnel or Tailscale Serve (keep `gateway.bind: "loopback"`)	Single-machine setups. See Tailscale and Web.

Command flow (what runs where)

One Gateway owns state and channels; nodes are peripherals. Example (Telegram message routed to a node tool):

SSH tunnel (CLI + tools)

With the tunnel up, openclaw health and openclaw status --deep reach the remote Gateway via ws://127.0.0.1:18789. openclaw gateway status, openclaw gateway health, openclaw gateway probe, and openclaw gateway call can also target a forwarded URL via --url.

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

CLI remote defaults

Persist a remote target so CLI commands use it by default:

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

{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "ws://192.168.0.202:18789",
      token: "your-token",
    },
  },
}

Credential precedence

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

주요 항목:

Explicit credentials (--token, --password, or a tool's gatewayToken) always win on call paths that accept explicit auth.
URL override safety:
CLI --url never reuses implicit config/env credentials.
Env OPENCLAW_GATEWAY_URL may use env credentials only (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
Local mode defaults:
token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (remote fallback only when the local token is unset)
password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (remote fallback only when the local password is unset)
Remote mode defaults:
token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
Node-host local-mode exception: gateway.remote.token / gateway.remote.password are ignored.
Remote probe/status token checks are strict by default: they use gateway.remote.token only (no local token fallback) when targeting remote mode.
Gateway env overrides use OPENCLAW_GATEWAY_* only.

Chat UI remote access

WebChat has no separate HTTP port; the SwiftUI chat UI connects directly to the Gateway WebSocket.

주요 항목:

Forward 18789 over SSH (see above), then connect clients to ws://127.0.0.1:18789.
For LAN/Tailnet direct mode, connect clients to the configured private ws:// or secure wss:// URL.
On macOS, the app's remote mode manages the selected transport automatically.

macOS app remote mode

The macOS menu bar app drives the same setup end-to-end: remote status checks, WebChat, and Voice Wake forwarding. Runbook: macOS remote access.

Security rules (remote/VPN)

Keep the Gateway loopback-only unless you are sure you need a bind.

주요 항목:

Loopback + SSH/Tailscale Serve is the safest default (no public exposure).
Plaintext ws:// is accepted for loopback, private/LAN (RFC 1918), link-local, CGNAT, .local, and .ts.net hosts. Public remote hosts must use wss://.
Non-loopback binds (lan/tailnet/custom, or auto when loopback is unavailable) must use Gateway auth: token, password, or an identity-aware reverse proxy with gateway.auth.mode: "trusted-proxy".
gateway.remote.token / .password are client credential sources; they do not configure server auth by themselves.
Local call paths can use gateway.remote.* as a fallback only when gateway.auth.* is unset.
If gateway.auth.token / gateway.auth.password is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking).
gateway.remote.tlsFingerprint pins the remote TLS cert for wss://, including both operator/control traffic and the companion node in macOS direct mode. Without a stored pin, macOS pins on first use only after normal system trust passes; self-signed or private-CA Gateways need an explicit fingerprint or Remote over SSH.
Tailscale Serve can authenticate Control UI/WebSocket traffic via identity headers when gateway.auth.allowTailscale: true. HTTP API endpoints do not use that header auth and instead follow the Gateway's normal HTTP auth mode. This tokenless flow assumes the Gateway host is trusted; set it to false for shared-secret auth everywhere.
Trusted-proxy auth expects a non-loopback identity-aware proxy by default. Same-host loopback reverse proxies require explicit gateway.auth.trustedProxy.allowLoopback = true.
Treat browser control like operator access: tailnet-only plus deliberate node pairing.

macOS: persistent SSH tunnel via LaunchAgent

For macOS clients, the easiest persistent setup uses an SSH LocalForward config entry plus a LaunchAgent that keeps the tunnel alive across reboots and crashes.

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

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

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

<?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>

Check if the tunnel is running

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

Restart the tunnel

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

Stop the tunnel

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

Config entry	What it does
`LocalForward 18789 127.0.0.1:18789`	Forwards local port 18789 to remote port 18789
`ssh -N`	SSH without executing remote commands (port forwarding only)
`KeepAlive`	Restarts the tunnel automatically if it crashes
`RunAtLoad`	Starts the tunnel when the LaunchAgent loads at login

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/remote
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

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

{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "ws://192.168.0.202:18789",
      token: "your-token",
    },
  },
}

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

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

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

Remote access

핵심 요약

Remote access using Gateway WS, SSH tunnels, and tailnets

한국어 가이드 범위: gateway/remote 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

The core idea
Topology options
Command flow (what runs where)
SSH tunnel (CLI + tools)
CLI remote defaults
Credential precedence
Chat UI remote access
macOS app remote mode
Security rules (remote/VPN)
macOS: persistent SSH tunnel via LaunchAgent
Check if the tunnel is running
Restart the tunnel
Stop the tunnel
관련 문서

상세 내용

본문

OpenClaw runs one Gateway (the master) on a host and connects every client to it. The Gateway owns sessions, auth profiles, channels, and state; everything else is a client.

주요 항목:

Operators (you, or the macOS app): direct LAN/Tailnet WebSocket is simplest when the Gateway is reachable; SSH tunneling is the universal fallback.
Nodes (iOS/Android and other devices): connect to the Gateway WebSocket (LAN/tailnet or SSH tunnel).

The core idea

Topology options

Setup	Where the Gateway runs	Best for
Always-on Gateway in your tailnet	Persistent host (VPS or home server), reached via Tailscale or SSH	Laptops that sleep often but need the agent always-on. See exe.dev (easy VM) or Hetzner (production VPS).
Home desktop	Desktop; laptop connects remotely via the macOS app's remote mode (Settings → Connection → OpenClaw runs)	Keeping the agent on hardware that stays powered on. Runbook: macOS remote access.
Laptop	Laptop, exposed safely via SSH tunnel or Tailscale Serve (keep `gateway.bind: "loopback"`)	Single-machine setups. See Tailscale and Web.

Command flow (what runs where)

One Gateway owns state and channels; nodes are peripherals. Example (Telegram message routed to a node tool):

SSH tunnel (CLI + tools)

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

CLI remote defaults

Persist a remote target so CLI commands use it by default:

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

{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "ws://192.168.0.202:18789",
      token: "your-token",
    },
  },
}

Credential precedence

주요 항목:

Explicit credentials (--token, --password, or a tool's gatewayToken) always win on call paths that accept explicit auth.
URL override safety:
CLI --url never reuses implicit config/env credentials.
Env OPENCLAW_GATEWAY_URL may use env credentials only (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
Local mode defaults:
token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (remote fallback only when the local token is unset)
password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (remote fallback only when the local password is unset)
Remote mode defaults:
token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
Node-host local-mode exception: gateway.remote.token / gateway.remote.password are ignored.
Remote probe/status token checks are strict by default: they use gateway.remote.token only (no local token fallback) when targeting remote mode.
Gateway env overrides use OPENCLAW_GATEWAY_* only.

Chat UI remote access

WebChat has no separate HTTP port; the SwiftUI chat UI connects directly to the Gateway WebSocket.

주요 항목:

Forward 18789 over SSH (see above), then connect clients to ws://127.0.0.1:18789.
For LAN/Tailnet direct mode, connect clients to the configured private ws:// or secure wss:// URL.
On macOS, the app's remote mode manages the selected transport automatically.

macOS app remote mode

The macOS menu bar app drives the same setup end-to-end: remote status checks, WebChat, and Voice Wake forwarding. Runbook: macOS remote access.

Security rules (remote/VPN)

Keep the Gateway loopback-only unless you are sure you need a bind.

주요 항목:

Loopback + SSH/Tailscale Serve is the safest default (no public exposure).
Plaintext ws:// is accepted for loopback, private/LAN (RFC 1918), link-local, CGNAT, .local, and .ts.net hosts. Public remote hosts must use wss://.
Non-loopback binds (lan/tailnet/custom, or auto when loopback is unavailable) must use Gateway auth: token, password, or an identity-aware reverse proxy with gateway.auth.mode: "trusted-proxy".
gateway.remote.token / .password are client credential sources; they do not configure server auth by themselves.
Local call paths can use gateway.remote.* as a fallback only when gateway.auth.* is unset.
If gateway.auth.token / gateway.auth.password is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking).
gateway.remote.tlsFingerprint pins the remote TLS cert for wss://, including both operator/control traffic and the companion node in macOS direct mode. Without a stored pin, macOS pins on first use only after normal system trust passes; self-signed or private-CA Gateways need an explicit fingerprint or Remote over SSH.
Tailscale Serve can authenticate Control UI/WebSocket traffic via identity headers when gateway.auth.allowTailscale: true. HTTP API endpoints do not use that header auth and instead follow the Gateway's normal HTTP auth mode. This tokenless flow assumes the Gateway host is trusted; set it to false for shared-secret auth everywhere.
Trusted-proxy auth expects a non-loopback identity-aware proxy by default. Same-host loopback reverse proxies require explicit gateway.auth.trustedProxy.allowLoopback = true.
Treat browser control like operator access: tailnet-only plus deliberate node pairing.

macOS: persistent SSH tunnel via LaunchAgent

For macOS clients, the easiest persistent setup uses an SSH LocalForward config entry plus a LaunchAgent that keeps the tunnel alive across reboots and crashes.

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

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

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

<?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>

Check if the tunnel is running

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

Restart the tunnel

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

Stop the tunnel

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

Config entry	What it does
`LocalForward 18789 127.0.0.1:18789`	Forwards local port 18789 to remote port 18789
`ssh -N`	SSH without executing remote commands (port forwarding only)
`KeepAlive`	Restarts the tunnel automatically if it crashes
`RunAtLoad`	Starts the tunnel when the LaunchAgent loads at login

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/remote
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

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

{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "ws://192.168.0.202:18789",
      token: "your-token",
    },
  },
}

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

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

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

Remote access

핵심 요약

문서 구성

상세 내용

본문

The core idea

Topology options

Command flow (what runs where)

SSH tunnel (CLI + tools)

CLI remote defaults

Credential precedence

Chat UI remote access

macOS app remote mode

Security rules (remote/VPN)

macOS: persistent SSH tunnel via LaunchAgent

Check if the tunnel is running

Restart the tunnel

Stop the tunnel

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Remote access

핵심 요약

문서 구성

상세 내용

본문

The core idea

Topology options

Command flow (what runs where)

SSH tunnel (CLI + tools)

CLI remote defaults

Credential precedence

Chat UI remote access

macOS app remote mode

Security rules (remote/VPN)

macOS: persistent SSH tunnel via LaunchAgent

Check if the tunnel is running

Restart the tunnel

Stop the tunnel

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드