​

Dostęp zdalny (SSH, tunele i tailnety)

• Dla operatorów (Ciebie / aplikacji macOS): tunelowanie SSH to uniwersalny mechanizm zapasowy.
• Dla węzłów (iOS/Android i przyszłe urządzenia): łącz się z gateway WebSocket (LAN/tailnet lub tunel SSH, jeśli to potrzebne).

​

Główna idea

• Gateway WebSocket nasłuchuje na local loopback na skonfigurowanym porcie (domyślnie 18789).
• Do użycia zdalnego przekazujesz ten port local loopback przez SSH (lub używasz tailnetu/VPN i tunelujesz mniej).

​

Typowe konfiguracje VPN/tailnet (gdzie znajduje się agent)

​

1) Zawsze aktywny Gateway w Twoim tailnecie (VPS lub serwer domowy)

• Najlepszy UX: ustaw gateway.bind: "loopback" i użyj Tailscale Serve dla Control UI.
• Mechanizm zapasowy: pozostaw loopback + tunel SSH z każdej maszyny, która potrzebuje dostępu.
• Przykłady: exe.dev (prosta VM) lub Hetzner (produkcyjny VPS).

​

2) Domowy desktop uruchamia Gateway, laptop służy do zdalnego sterowania

• Użyj trybu aplikacji macOS Remote over SSH (Ustawienia → Ogólne → „OpenClaw runs”).
• Aplikacja otwiera i zarządza tunelem, więc WebChat + kontrole stanu „po prostu działają”.

​

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

• tunel SSH do laptopa z innych maszyn, albo
• Tailscale Serve dla Control UI i pozostawienie Gateway dostępnego tylko przez loopback.

​

Przepływ poleceń (co działa gdzie)

• Wiadomość Telegram trafia do Gateway.
• Gateway uruchamia agenta i decyduje, czy wywołać narzędzie węzła.
• Gateway wywołuje węzeł przez Gateway WebSocket (node.* RPC).
• Węzeł zwraca wynik; Gateway odsyła odpowiedź do Telegrama.

• Węzły nie uruchamiają usługi gateway. Na host powinien przypadać tylko jeden gateway, chyba że celowo uruchamiasz odizolowane profile (zobacz Wiele gateway).
• „Tryb węzła” w aplikacji macOS to po prostu klient węzła przez Gateway WebSocket.

​

Tunel SSH (CLI + narzędzia)

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

• openclaw health i openclaw status --deep docierają teraz do zdalnego gateway przez ws://127.0.0.1:18789.
• openclaw gateway status, openclaw gateway health, openclaw gateway probe i openclaw gateway call mogą też kierować ruch do przekazanego URL przez --url, gdy jest to potrzebne.

​

Domyślne ustawienia zdalne CLI

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

​

Pierwszeństwo poświadczeń

• Jawne poświadczenia (--token, --password lub narzędzie gatewayToken) zawsze mają pierwszeństwo w ścieżkach wywołań, które akceptują jawne uwierzytelnianie.
• Bezpieczeństwo nadpisania URL:
  • Nadpisania URL CLI (--url) nigdy nie używają ponownie niejawnych poświadczeń z konfiguracji/env.
  • Nadpisania URL przez env (OPENCLAW_GATEWAY_URL) mogą używać tylko poświadczeń z env (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Domyślne ustawienia trybu lokalnego:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (fallback zdalny ma zastosowanie tylko wtedy, gdy lokalne wejście tokena uwierzytelniania nie jest ustawione)
  • hasło: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (fallback zdalny ma zastosowanie tylko wtedy, gdy lokalne wejście hasła uwierzytelniania nie jest ustawione)
• Domyślne ustawienia trybu zdalnego:
  • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • hasło: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Wyjątek hosta węzła w trybie lokalnym: gateway.remote.token / gateway.remote.password są ignorowane.
• Zdalne kontrole tokena probe/status są domyślnie ścisłe: używają tylko gateway.remote.token (bez fallbacku do lokalnego tokena) przy kierowaniu do trybu zdalnego.
• Nadpisania env gateway używają tylko OPENCLAW_GATEWAY_*.

​

Interfejs czatu przez SSH

• Przekaż port 18789 przez SSH (zobacz wyżej), a następnie połącz klientów z ws://127.0.0.1:18789.
• W systemie macOS preferuj tryb aplikacji „Remote over SSH”, który zarządza tunelem automatycznie.

​

Aplikacja macOS „Remote over SSH”

​

Zasady bezpieczeństwa (zdalnie/VPN)

• Loopback + SSH/Tailscale Serve to najbezpieczniejsza wartość domyślna (brak publicznej ekspozycji).
• Niejawnie szyfrowane ws:// jest domyślnie ograniczone do loopback. Dla zaufanych sieci prywatnych ustaw OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 w procesie klienta jako rozwiązanie awaryjne.
• Bindowanie poza loopback (lan/tailnet/custom lub auto, gdy loopback jest niedostępny) musi używać uwierzytelniania gateway: tokenu, hasła albo reverse proxy uwzględniającego tożsamość z gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password są źródłami poświadczeń klienta. Same z siebie nie konfigurują uwierzytelniania serwera.
• Lokalne ścieżki wywołań mogą używać gateway.remote.* jako fallback tylko wtedy, gdy gateway.auth.* nie jest ustawione.
• Jeśli gateway.auth.token / gateway.auth.password są jawnie skonfigurowane przez SecretRef i nierozwiązane, rozwiązywanie kończy się bezpieczną odmową (bez maskowania przez zdalny fallback).
• gateway.remote.tlsFingerprint przypina zdalny certyfikat TLS przy użyciu wss://.
• Tailscale Serve może uwierzytelniać ruch Control UI/WebSocket przez nagłówki tożsamości, gdy gateway.auth.allowTailscale: true; endpointy HTTP API nie używają tego uwierzytelniania nagłówkami Tailscale i zamiast tego stosują zwykły tryb uwierzytelniania HTTP gateway. Ten przepływ bez tokena zakłada, że host gateway jest zaufany. Ustaw false, jeśli chcesz uwierzytelniania współdzielonym sekretem wszędzie.
• Uwierzytelnianie trusted-proxy jest przeznaczone tylko dla konfiguracji proxy uwzględniających tożsamość poza loopback. Reverse proxy z loopback na tym samym hoście nie spełniają wymagań gateway.auth.mode: "trusted-proxy".
• Traktuj sterowanie przeglądarką jak dostęp operatora: tylko tailnet + celowe parowanie węzłów.

​

macOS: trwały tunel SSH przez LaunchAgent

​

Krok 1: dodaj konfigurację SSH

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

​

Krok 2: skopiuj klucz SSH (jednorazowo)

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

​

Krok 3: skonfiguruj token gateway

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

​

Krok 4: utwórz LaunchAgent

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

​

Krok 5: załaduj LaunchAgent

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

​

Rozwiązywanie problemów

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

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

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