Przejdź do głównej treści

​
Zdalny dostęp (SSH, tunele i sieci tailnet)

To repozytorium obsługuje tryb „zdalnie przez SSH” poprzez utrzymywanie pojedynczego Gateway (mastera) uruchomionego na dedykowanym hoście (desktop/serwer) oraz łączenie z nim klientów.
  • Dla operatorów (Ty / aplikacja na macOS): tunelowanie SSH jest uniwersalnym rozwiązaniem awaryjnym.
  • Dla węzłów (iOS/Android oraz przyszłe urządzenia): połączenie z WebSocketem Gateway (LAN/tailnet lub tunel SSH w razie potrzeby).

​
Główna idea

  • WebSocket Gateway wiąże się z loopback na skonfigurowanym porcie (domyślnie 18789).
  • Do użytku zdalnego przekazujesz ten port loopback przez SSH (lub używasz tailnet/VPN i tunelujesz rzadziej).

​
Typowe konfiguracje VPN/tailnet (gdzie działa agent)

Traktuj host Gateway jako „miejsce, w którym działa agent”. To on posiada sesje, profile uwierzytelniania, kanały i stan. Twój laptop/desktop (oraz węzły) łączą się z tym hostem.

​
1. Gateway zawsze włączony w Twojej sieci tailnet (VPS lub serwer domowy)

Uruchom Gateway na hoście stałym i uzyskuj do niego dostęp przez Tailscale lub SSH.
  • Najlepsze UX: zachowaj gateway.bind: "loopback" i użyj Tailscale Serve dla interfejsu Control UI.
  • Fallback: zachowaj loopback + tunel SSH z dowolnej maszyny, która potrzebuje dostępu.
  • Przykłady: exe.dev (łatwa VM) lub Hetzner (produkcyjny VPS).
To rozwiązanie jest idealne, gdy laptop często przechodzi w uśpienie, a chcesz, aby agent był zawsze dostępny.

​
2. Domowy desktop uruchamia Gateway, laptop jest zdalnym sterowaniem

Laptop nie uruchamia agenta. Łączy się zdalnie:
  • Użyj trybu Remote over SSH w aplikacji na macOS (Ustawienia → Ogólne → „OpenClaw runs”).
  • Aplikacja otwiera i zarządza tunelem, więc WebChat + kontrole stanu „po prostu działają”.
Runbook: zdalny dostęp na macOS.

​
3. Laptop uruchamia Gateway, zdalny dostęp z innych maszyn

Zachowaj Gateway lokalnie, ale wystaw go bezpiecznie:
  • Tunel SSH do laptopa z innych maszyn lub
  • Udostępnij Control UI przez Tailscale Serve i pozostaw Gateway tylko na loopback.
Przewodnik: Tailscale oraz Przegląd Web.

​
Przepływ poleceń (co uruchamia się gdzie)

Jedna usługa gateway posiada stan + kanały. Węzły są peryferiami. Przykładowy przepływ (Telegram → węzeł):
  • Wiadomość z Telegrama trafia do Gateway.
  • Gateway uruchamia agenta i decyduje, czy wywołać narzędzie w węźle.
  • Gateway wywołuje węzeł przez WebSocket Gateway (RPC node.*).
  • Węzeł zwraca wynik; Gateway odsyła odpowiedź do Telegrama.
Uwagi:
  • Węzły nie uruchamiają usługi gateway. Na jednym hoście powinien działać tylko jeden gateway, chyba że celowo uruchamiasz odizolowane profile (zobacz Wiele gatewayów).
  • „Tryb węzła” w aplikacji na macOS to po prostu klient węzła przez WebSocket Gateway.

​
Tunel SSH (CLI + narzędzia)

Utwórz lokalny tunel do zdalnego Gateway WS: 
ssh -N -L 18789:127.0.0.1:18789 user@host
Z tunelem w górę:
  • openclaw health oraz openclaw status --deep docierają teraz do zdalnego gateway przez ws://127.0.0.1:18789.
  • openclaw gateway {status,health,send,agent,call} może również wskazywać przekazany URL przez --url, gdy jest to potrzebne.
Uwaga: zastąp 18789 swoją skonfigurowaną wartością gateway.port (lub --port/OPENCLAW_GATEWAY_PORT). Uwaga: gdy przekażesz --url, CLI nie korzysta z konfiguracji ani poświadczeń środowiskowych. Jawnie dołącz --token lub --password. Brak jawnych poświadczeń jest błędem.

​
Domyślne ustawienia zdalne CLI

Możesz zapisać zdalny cel, aby polecenia CLI używały go domyślnie: 
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}
Gdy gateway jest dostępny tylko przez loopback, pozostaw URL jako ws://127.0.0.1:18789 i najpierw otwórz tunel SSH.

​
Interfejs czatu przez SSH

WebChat nie używa już osobnego portu HTTP. Interfejs czatu SwiftUI łączy się bezpośrednio z WebSocketem Gateway.
  • Przekaż 18789 przez SSH (patrz wyżej), a następnie połącz klientów z ws://127.0.0.1:18789.
  • Na macOS preferuj tryb „Remote over SSH” w aplikacji, który automatycznie zarządza tunelem.

​
Aplikacja na macOS „Remote over SSH”

Aplikacja w pasku menu macOS może obsłużyć tę konfigurację end-to-end (zdalne kontrole stanu, WebChat oraz przekazywanie Voice Wake). Runbook: zdalny dostęp na macOS.

​
Zasady bezpieczeństwa (zdalnie/VPN)

W skrócie: utrzymuj Gateway tylko na loopback, chyba że masz pewność, że potrzebujesz bindowania.
  • Loopback + SSH/Tailscale Serve to najbezpieczniejsza domyślna opcja (brak publicznej ekspozycji).
  • Bindowania poza loopback (lan/tailnet/custom lub auto, gdy loopback jest niedostępny) muszą używać tokenów/hasła uwierzytelniania.
  • gateway.remote.token jest wyłącznie do zdalnych wywołań CLI — nie włącza lokalnego uwierzytelniania.
  • gateway.remote.tlsFingerprint przypina zdalny certyfikat TLS podczas użycia wss://.
  • Tailscale Serve może uwierzytelniać przez nagłówki tożsamości, gdy gateway.auth.allowTailscale: true. Ustaw na false, jeśli zamiast tego chcesz używać tokenów/hasła.
  • Traktuj kontrolę w przeglądarce jak dostęp operatora: tylko w obrębie tailnet + świadome parowanie węzłów.
Dogłębnie: Bezpieczeństwo.