Remote control

Remote control 문서는 OpenClaw 공식 문서(platforms/mac/remote)를 한국어로 정리한 가이드입니다. macOS app flow for controlling a remote OpenClaw gateway 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

macOS app flow for controlling a remote OpenClaw gateway

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

문서 구성

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

Modes
Remote transports
Prereqs on the remote host
macOS app setup
Web Chat
Permissions
Security notes
WhatsApp login flow (remote)
트러블슈팅
Notification sounds
관련 문서

상세 내용

본문

This flow lets the macOS app act as a full remote control for an OpenClaw gateway running on another host (desktop/server). The app connects directly to trusted LAN/Tailnet gateway URLs, or manages an SSH tunnel when the remote gateway is loopback-only. Health checks, Voice Wake forwarding, and Web Chat reuse the same remote configuration from Settings -> General.

Modes

주요 항목:

Local (this Mac): everything runs on the laptop; no SSH involved.
Remote over SSH (default): OpenClaw commands run on the remote host. The app opens an SSH connection with -o BatchMode, your chosen identity/key, and a local port-forward.
Remote direct (ws/wss): no SSH tunnel; the app connects to the gateway URL directly (LAN, Tailscale, Tailscale Serve, or a public HTTPS reverse proxy).

Remote transports

The app disables SSH connection multiplexing and post-authentication backgrounding for its own SSH processes so it can monitor and restart the exact process, even if the selected alias enables ControlMaster or ForkAfterAuthentication.

주요 항목:

SSH tunnel (default): uses ssh -N -L ... to forward the gateway port to localhost. The gateway sees the node's IP as 127.0.0.1 because the tunnel is loopback.
Direct (ws/wss): connects straight to the gateway URL. The gateway sees the real client IP.

Prereqs on the remote host

Install Node + pnpm and build/install the OpenClaw CLI (pnpm install && pnpm build && pnpm link --global). 2. Ensure openclaw is on PATH for non-interactive shells (symlink into /usr/local/bin or /opt/homebrew/bin if needed). 3. For SSH transport: set up key-based SSH auth. Tailscale IPs are recommended for stable reachability off-LAN.

macOS app setup

To preconfigure the app without the welcome flow, over SSH:

주요 항목:

Transport: SSH tunnel or Direct (ws/wss).
SSH target: user@host (optional :port). If the gateway is on the same LAN and advertises Bonjour, pick it from the discovered list to auto-fill this field.
Gateway URL (Direct only): wss://gateway.example.ts.net (or ws://... for local/LAN).
Identity file (advanced): path to your key.
Project root (advanced): remote checkout path used for commands.
CLI path (advanced): optional path to a runnable openclaw entrypoint/binary (auto-filled when advertised).

openclaw-mac configure-remote \
  --ssh-target user@gateway-host \
  --local-port 18789 \
  --remote-port 18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

openclaw-mac configure-remote \
  --direct-url ws://192.168.0.202:18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

Web Chat

주요 항목:

SSH tunnel: connects to the gateway over the forwarded WebSocket control port (default 18789).
Direct (ws/wss): connects straight to the configured gateway URL.
There is no separate Web Chat HTTP server.

Permissions

주요 항목:

The remote host needs the same TCC approvals as local (Automation, Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications). Run onboarding on that machine once to grant them.
Nodes advertise their permission state via node.list / node.describe so agents know what is available.

Security notes

주요 항목:

Prefer loopback binds on the remote host and connect via SSH, Tailscale Serve, or a trusted Tailnet/LAN direct URL.
SSH tunneling requires an already-trusted host key by default. Trust the host key first (add it to the configured known-hosts file), or explicitly set gateway.remote.sshHostKeyPolicy: "openssh" for a managed alias whose OpenSSH trust policy you accept.
If you bind the Gateway to a non-loopback interface, require valid Gateway auth: token, password, or an identity-aware reverse proxy with gateway.auth.mode: "trusted-proxy".
Direct wss:// connections apply one certificate policy to both operator/control traffic and the Mac companion node. Set gateway.remote.tlsFingerprint for an explicit pin. Without one, the app records a first-use pin only after normal macOS trust succeeds.
See Security and Tailscale.

주요 항목:

Run openclaw channels login --channel whatsapp --verbose on the remote host. Scan the QR with WhatsApp on your phone.
Re-run login on that host if auth expires. The health check surfaces link problems.

트러블슈팅

Symptom	Cause / fix
`exit 127` / not found	`openclaw` is not on PATH for non-login shells. Add it to `/etc/paths`, your shell rc, or symlink into `/usr/local/bin`/`/opt/homebrew/bin`.
Health probe failed	Check SSH reachability, PATH, and that Baileys (WhatsApp) is logged in (`openclaw status --json`).
Web Chat stuck	Confirm the gateway is running on the remote host and the forwarded port matches the gateway WS port; the UI requires a healthy WS connection.
Node IP shows `127.0.0.1`	Expected with the SSH tunnel. Switch Transport to Direct (ws/wss) if you want the gateway to see the real client IP.
Dashboard works but Mac capabilities are offline	The operator/control connection is healthy, but the companion node connection is not connected or is missing its command surface. Open the menu bar device section and check whether the Mac is `paired · disconnected`. Direct `wss://` operator and node connections use the same configured or stored certificate policy. For trusted `wss://.ts.net` Tailscale Serve endpoints, stale stored leaf pins are replaced after certificate rotation and retried automatically. Configured pins never rotate automatically; update `gateway.remote.tlsFingerprint` after reviewing the new certificate, or switch to Remote over SSH*.
Voice Wake	Trigger phrases forward automatically in remote mode; no separate forwarder is needed.

Notification sounds

Pick sounds per notification from scripts with openclaw nodes notify, for example:

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw-mac configure-remote \
  --ssh-target user@gateway-host \
  --local-port 18789 \
  --remote-port 18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

openclaw-mac configure-remote \
  --direct-url ws://192.168.0.202:18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

Remote control

핵심 요약

macOS app flow for controlling a remote OpenClaw gateway

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

문서 구성

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

Modes
Remote transports
Prereqs on the remote host
macOS app setup
Web Chat
Permissions
Security notes
WhatsApp login flow (remote)
트러블슈팅
Notification sounds
관련 문서

상세 내용

본문

Modes

주요 항목:

Local (this Mac): everything runs on the laptop; no SSH involved.
Remote over SSH (default): OpenClaw commands run on the remote host. The app opens an SSH connection with -o BatchMode, your chosen identity/key, and a local port-forward.
Remote direct (ws/wss): no SSH tunnel; the app connects to the gateway URL directly (LAN, Tailscale, Tailscale Serve, or a public HTTPS reverse proxy).

Remote transports

주요 항목:

SSH tunnel (default): uses ssh -N -L ... to forward the gateway port to localhost. The gateway sees the node's IP as 127.0.0.1 because the tunnel is loopback.
Direct (ws/wss): connects straight to the gateway URL. The gateway sees the real client IP.

Prereqs on the remote host

Install Node + pnpm and build/install the OpenClaw CLI (pnpm install && pnpm build && pnpm link --global). 2. Ensure openclaw is on PATH for non-interactive shells (symlink into /usr/local/bin or /opt/homebrew/bin if needed). 3. For SSH transport: set up key-based SSH auth. Tailscale IPs are recommended for stable reachability off-LAN.

macOS app setup

To preconfigure the app without the welcome flow, over SSH:

주요 항목:

Transport: SSH tunnel or Direct (ws/wss).
SSH target: user@host (optional :port). If the gateway is on the same LAN and advertises Bonjour, pick it from the discovered list to auto-fill this field.
Gateway URL (Direct only): wss://gateway.example.ts.net (or ws://... for local/LAN).
Identity file (advanced): path to your key.
Project root (advanced): remote checkout path used for commands.
CLI path (advanced): optional path to a runnable openclaw entrypoint/binary (auto-filled when advertised).

openclaw-mac configure-remote \
  --ssh-target user@gateway-host \
  --local-port 18789 \
  --remote-port 18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

openclaw-mac configure-remote \
  --direct-url ws://192.168.0.202:18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

Web Chat

주요 항목:

SSH tunnel: connects to the gateway over the forwarded WebSocket control port (default 18789).
Direct (ws/wss): connects straight to the configured gateway URL.
There is no separate Web Chat HTTP server.

Permissions

주요 항목:

The remote host needs the same TCC approvals as local (Automation, Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications). Run onboarding on that machine once to grant them.
Nodes advertise their permission state via node.list / node.describe so agents know what is available.

Security notes

주요 항목:

Prefer loopback binds on the remote host and connect via SSH, Tailscale Serve, or a trusted Tailnet/LAN direct URL.
SSH tunneling requires an already-trusted host key by default. Trust the host key first (add it to the configured known-hosts file), or explicitly set gateway.remote.sshHostKeyPolicy: "openssh" for a managed alias whose OpenSSH trust policy you accept.
If you bind the Gateway to a non-loopback interface, require valid Gateway auth: token, password, or an identity-aware reverse proxy with gateway.auth.mode: "trusted-proxy".
Direct wss:// connections apply one certificate policy to both operator/control traffic and the Mac companion node. Set gateway.remote.tlsFingerprint for an explicit pin. Without one, the app records a first-use pin only after normal macOS trust succeeds.
See Security and Tailscale.

주요 항목:

Run openclaw channels login --channel whatsapp --verbose on the remote host. Scan the QR with WhatsApp on your phone.
Re-run login on that host if auth expires. The health check surfaces link problems.

트러블슈팅

Symptom	Cause / fix
`exit 127` / not found	`openclaw` is not on PATH for non-login shells. Add it to `/etc/paths`, your shell rc, or symlink into `/usr/local/bin`/`/opt/homebrew/bin`.
Health probe failed	Check SSH reachability, PATH, and that Baileys (WhatsApp) is logged in (`openclaw status --json`).
Web Chat stuck	Confirm the gateway is running on the remote host and the forwarded port matches the gateway WS port; the UI requires a healthy WS connection.
Node IP shows `127.0.0.1`	Expected with the SSH tunnel. Switch Transport to Direct (ws/wss) if you want the gateway to see the real client IP.
Dashboard works but Mac capabilities are offline	The operator/control connection is healthy, but the companion node connection is not connected or is missing its command surface. Open the menu bar device section and check whether the Mac is `paired · disconnected`. Direct `wss://` operator and node connections use the same configured or stored certificate policy. For trusted `wss://.ts.net` Tailscale Serve endpoints, stale stored leaf pins are replaced after certificate rotation and retried automatically. Configured pins never rotate automatically; update `gateway.remote.tlsFingerprint` after reviewing the new certificate, or switch to Remote over SSH*.
Voice Wake	Trigger phrases forward automatically in remote mode; no separate forwarder is needed.

Notification sounds

Pick sounds per notification from scripts with openclaw nodes notify, for example:

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw-mac configure-remote \
  --ssh-target user@gateway-host \
  --local-port 18789 \
  --remote-port 18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

openclaw-mac configure-remote \
  --direct-url ws://192.168.0.202:18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

Remote control

핵심 요약

문서 구성

상세 내용

본문

Modes

Remote transports

Prereqs on the remote host

macOS app setup

Web Chat

Permissions

Security notes

트러블슈팅

Notification sounds

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Remote control

핵심 요약

문서 구성

상세 내용

본문

Modes

Remote transports

Prereqs on the remote host

macOS app setup

Web Chat

Permissions

Security notes

트러블슈팅

Notification sounds

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Remote control

핵심 요약

문서 구성

상세 내용

본문

Modes

Remote transports

Prereqs on the remote host

macOS app setup

Web Chat

Permissions

Security notes

WhatsApp login flow (remote)

트러블슈팅

Notification sounds

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Remote control

핵심 요약

문서 구성

상세 내용

본문

Modes

Remote transports

Prereqs on the remote host

macOS app setup

Web Chat

Permissions

Security notes

WhatsApp login flow (remote)

트러블슈팅

Notification sounds

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드