Dostęp zdalny

• Operatorzy (Ty lub aplikacja macOS): bezpośrednie połączenie WebSocket przez LAN/Tailnet jest najprostsze, gdy Gateway jest osiągalny; tunelowanie SSH stanowi uniwersalne rozwiązanie awaryjne.
• Node’y (iOS/Android i inne urządzenia): łączą się z WebSocketem Gateway (przez LAN/Tailnet lub tunel SSH).

​

Główna idea

​

Opcje topologii

​

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

1. Wiadomość Telegram dociera do Gateway.
2. Gateway uruchamia agenta, który decyduje, czy wywołać narzędzie Node’a.
3. Gateway wywołuje Node przez WebSocket Gateway (RPC node.invoke).
4. Node zwraca wynik; Gateway odpowiada w Telegramie.

​

Tunel SSH (CLI i narzędzia)

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

​

Domyślne ustawienia zdalne CLI

{
  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",
    },
  },
}

​

Pierwszeństwo poświadczeń

• Jawne poświadczenia (--token, --password lub gatewayToken narzędzia) zawsze mają pierwszeństwo w ścieżkach wywołań obsługujących jawne uwierzytelnianie.
• Bezpieczeństwo nadpisania adresu URL:
  • Opcja CLI --url nigdy nie używa niejawnych poświadczeń z konfiguracji ani środowiska.
  • Zmienna środowiskowa OPENCLAW_GATEWAY_URL może używać wyłącznie poświadczeń ze środowiska (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Domyślne ustawienia trybu lokalnego:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (zdalna wartość awaryjna tylko wtedy, gdy token lokalny nie jest ustawiony)
  • hasło: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (zdalna wartość awaryjna tylko wtedy, gdy hasło lokalne 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 trybu lokalnego hosta Node’a: gateway.remote.token / gateway.remote.password są ignorowane.
• Zdalne kontrole tokena podczas sondowania/sprawdzania stanu są domyślnie rygorystyczne: gdy celem jest tryb zdalny, używają wyłącznie gateway.remote.token (bez awaryjnego użycia tokena lokalnego).
• Nadpisania środowiskowe Gateway używają wyłącznie OPENCLAW_GATEWAY_*.

​

Zdalny dostęp do interfejsu czatu

• Przekieruj 18789 przez SSH (zobacz wyżej), a następnie połącz klientów z ws://127.0.0.1:18789.
• W trybie bezpośrednim LAN/Tailnet połącz klientów ze skonfigurowanym prywatnym adresem ws:// lub bezpiecznym adresem URL wss://.
• W systemie macOS tryb zdalny aplikacji automatycznie zarządza wybranym transportem.

​

Tryb zdalny aplikacji macOS

​

Reguły bezpieczeństwa (dostęp zdalny/VPN)

• Loopback + SSH/Tailscale Serve to najbezpieczniejsze ustawienie domyślne (bez publicznego udostępniania).
• Nieszyfrowany protokół ws:// jest akceptowany dla interfejsu loopback, sieci prywatnych/LAN (RFC 1918), adresów lokalnych dla łącza, CGNAT oraz hostów .local i .ts.net. Publiczne hosty zdalne muszą używać wss://.
• Powiązania inne niż loopback (lan/tailnet/custom lub auto, gdy loopback jest niedostępny) muszą korzystać z uwierzytelniania Gateway: tokena, hasła lub odwrotnego serwera proxy rozpoznającego tożsamość z ustawieniem gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password są źródłami poświadczeń klienta; same nie konfigurują uwierzytelniania serwera.
• Lokalne ścieżki wywołań mogą używać gateway.remote.* jako wartości awaryjnej tylko wtedy, gdy gateway.auth.* nie jest ustawione.
• Jeśli gateway.auth.token / gateway.auth.password skonfigurowano jawnie za pomocą SecretRef, ale nie uda się ich rozpoznać, rozpoznawanie kończy się bezpieczną odmową (bez maskującego awaryjnego użycia ustawień zdalnych).
• gateway.remote.tlsFingerprint przypina zdalny certyfikat TLS dla wss://, również w trybie bezpośrednim macOS. Bez zapisanego odcisku palca system macOS przypina certyfikat przy pierwszym użyciu dopiero po pomyślnym przejściu standardowej weryfikacji zaufania systemowego; Gateway z certyfikatem samopodpisanym lub prywatnym urzędem certyfikacji wymaga jawnego odcisku palca albo połączenia zdalnego przez SSH.
• Tailscale Serve może uwierzytelniać ruch interfejsu sterowania/WebSocket za pomocą nagłówków tożsamości, gdy gateway.auth.allowTailscale: true. Punkty końcowe API HTTP nie używają tego uwierzytelniania nagłówkowego i zamiast tego stosują standardowy tryb uwierzytelniania HTTP Gateway. Ten przepływ bez tokena zakłada, że host Gateway jest zaufany; ustaw wartość false, aby wszędzie używać uwierzytelniania współdzielonym sekretem.
• Uwierzytelnianie zaufanego serwera proxy domyślnie oczekuje serwera proxy rozpoznającego tożsamość, który nie działa na interfejsie loopback. Odwrotne serwery proxy działające na tym samym hoście i interfejsie loopback wymagają jawnego ustawienia gateway.auth.trustedProxy.allowLoopback = true.
• Traktuj sterowanie przez przeglądarkę jak dostęp operatora: tylko w tailnecie i z celowym parowaniem Node’a.

​

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

# Sprawdź, czy tunel działa
ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

# Uruchom tunel ponownie
launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

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

​

Powiązane materiały

• Tailscale
• Uwierzytelnianie
• Konfiguracja zdalnego Gateway