Bediening op afstand

Met deze stroom kan de macOS-app fungeren als volledige afstandsbediening voor een OpenClaw-Gateway die op een andere host (desktop/server) draait. Dit is de functie Extern via SSH (extern uitvoeren) van de app. Alle functies-statuscontroles, doorsturen van spraakactivering en webchat-gebruiken dezelfde externe SSH-configuratie uit Instellingen → Algemeen.

# Modi

• Lokaal (deze Mac): Alles draait op de laptop. Er is geen SSH bij betrokken.
• Extern via SSH (standaard): OpenClaw-opdrachten worden uitgevoerd op de externe host. De Mac-app opent een SSH-verbinding met -o BatchMode, plus je gekozen identiteit/sleutel en een lokale poortdoorsturing.
• Extern direct (ws/wss): Geen SSH-tunnel. De Mac-app maakt rechtstreeks verbinding met de Gateway-URL (bijvoorbeeld via Tailscale Serve of een openbare HTTPS-reverseproxy).

# Externe transporten

Externe modus ondersteunt twee transporten:

• SSH-tunnel (standaard): Gebruikt ssh -N -L ... om de Gateway-poort door te sturen naar localhost. De Gateway ziet het IP-adres van de Node als 127.0.0.1, omdat de tunnel loopback is.
• Direct (ws/wss): Maakt rechtstreeks verbinding met de Gateway-URL. De Gateway ziet het echte client-IP-adres.

In SSH-tunnelmodus worden gevonden LAN-/tailnet-hostnamen opgeslagen als gateway.remote.sshTarget. De app houdt gateway.remote.url op het lokale tunneleindpunt, bijvoorbeeld ws://127.0.0.1:18789, zodat CLI, webchat en de lokale Node-hostservice allemaal hetzelfde veilige loopback-transport gebruiken.

Browserautomatisering in externe modus is eigendom van de CLI-Node-host, niet van de native macOS-app-Node. De app start waar mogelijk de geïnstalleerde Node-hostservice; als je browserbesturing vanaf die Mac nodig hebt, installeer/start die dan met openclaw node install ... en openclaw node start (of voer openclaw node run ... op de voorgrond uit), en richt je vervolgens op die browser-capabele Node.

# Vereisten op de externe host

1. Installeer Node + pnpm en bouw/installeer de OpenClaw-CLI (pnpm install && pnpm build && pnpm link --global).
2. Zorg dat openclaw op PATH staat voor niet-interactieve shells (maak indien nodig een symlink naar /usr/local/bin of /opt/homebrew/bin).
3. Open SSH met sleutelverificatie. We raden Tailscale-IP-adressen aan voor stabiele bereikbaarheid buiten het LAN.

# macOS-app instellen

1. Open Instellingen → Algemeen.
2. Kies onder OpenClaw draait de optie Extern via SSH en stel het volgende in:
   • Transport: SSH-tunnel of Direct (ws/wss).
   • SSH-doel: user@host (optioneel :port).
     • Als de Gateway zich op hetzelfde LAN bevindt en Bonjour adverteert, kies je deze uit de ontdekte lijst om dit veld automatisch in te vullen.
   • Gateway-URL (alleen Direct): wss://gateway.example.ts.net (of ws://... voor lokaal/LAN).
   • Identiteitsbestand (geavanceerd): pad naar je sleutel.
   • Projectroot (geavanceerd): extern checkout-pad dat voor opdrachten wordt gebruikt.
   • CLI-pad (geavanceerd): optioneel pad naar een uitvoerbaar openclaw-startpunt/binary (automatisch ingevuld wanneer geadverteerd).
3. Druk op Extern testen. Succes geeft aan dat de externe openclaw status --json correct draait. Mislukkingen betekenen meestal PATH-/CLI-problemen; exit 127 betekent dat de CLI extern niet wordt gevonden.
4. Statuscontroles en webchat lopen nu automatisch via deze SSH-tunnel.

# Webchat

• SSH-tunnel: Webchat maakt verbinding met de Gateway via de doorgestuurde WebSocket-besturingspoort (standaard 18789).
• Direct (ws/wss): Webchat maakt rechtstreeks verbinding met de geconfigureerde Gateway-URL.
• Er is geen aparte WebChat-HTTP-server meer.

# Machtigingen

• De externe host heeft dezelfde TCC-goedkeuringen nodig als lokaal (Automatisering, Toegankelijkheid, Schermopname, Microfoon, Spraakherkenning, Meldingen). Voer onboarding op die machine uit om ze eenmalig te verlenen.
• Nodes adverteren hun machtigingsstatus via node.list / node.describe, zodat agents weten wat beschikbaar is.

# Beveiligingsnotities

• Geef de voorkeur aan loopback-bindings op de externe host en maak verbinding via SSH of Tailscale.
• SSH-tunneling gebruikt strikte controle van hostsleutels; vertrouw eerst de hostsleutel, zodat deze bestaat in ~/.ssh/known_hosts.
• Als je de Gateway aan een niet-loopback-interface bindt, vereis dan geldige Gateway-authenticatie: token, wachtwoord of een identity-aware reverseproxy met gateway.auth.mode: "trusted-proxy".
• Zie Beveiliging en Tailscale.

# WhatsApp-inlogstroom (extern)

• Voer openclaw channels login --verbose op de externe host uit. Scan de QR-code met WhatsApp op je telefoon.
• Voer opnieuw login uit op die host als de authenticatie verloopt. De statuscontrole toont verbindingsproblemen.

# Probleemoplossing

• exit 127 / niet gevonden: openclaw staat niet op PATH voor niet-login-shells. Voeg het toe aan /etc/paths, je shell-rc, of maak een symlink naar /usr/local/bin//opt/homebrew/bin.
• Statusprobe mislukt: controleer SSH-bereikbaarheid, PATH en of Baileys is ingelogd (openclaw status --json).
• Webchat blijft hangen: bevestig dat de Gateway op de externe host draait en dat de doorgestuurde poort overeenkomt met de Gateway-WS-poort; de UI vereist een gezonde WS-verbinding.
• Node-IP toont 127.0.0.1: verwacht bij de SSH-tunnel. Zet Transport op Direct (ws/wss) als je wilt dat de Gateway het echte client-IP-adres ziet.
• Dashboard werkt maar Mac-mogelijkheden zijn offline: dit betekent dat de operator-/besturingsverbinding van de app gezond is, maar dat de companion-Node-verbinding niet verbonden is of zijn opdrachtoppervlak mist. Open het apparaatgedeelte in de menubalk en controleer of de Mac paired · disconnected is. Voor wss://*.ts.net Tailscale Serve-eindpunten detecteert de app verouderde legacy TLS-leaf-pins na certificaatrotatie, wist de verouderde pin wanneer macOS het nieuwe certificaat vertrouwt, en probeert automatisch opnieuw. Als het certificaat niet door het systeem wordt vertrouwd of de host geen Tailscale Serve-naam is, controleer dan het certificaat of schakel over naar Extern via SSH.
• Spraakactivering: triggerzinnen worden automatisch doorgestuurd in externe modus; er is geen aparte doorstuurder nodig.

# Meldingsgeluiden

Kies geluiden per melding vanuit scripts met openclaw en node.invoke, bijvoorbeeld:

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

Er is geen globale schakelaar voor "standaardgeluid" meer in de app; aanroepers kiezen per verzoek een geluid (of geen geluid).

# Gerelateerd

• macOS-app
• Externe toegang