​

Remote access (SSH, tüneller ve tailnet’ler)

• Operatörler için (siz / macOS uygulaması): SSH tünelleme evrensel geri dönüş seçeneğidir.
• Düğümler için (iOS/Android ve gelecekteki cihazlar): gerektiğinde Gateway WebSocket’e bağlanın (LAN/tailnet veya SSH tüneli üzerinden).

​

Temel fikir

• Gateway WebSocket, yapılandırdığınız portta loopback üzerine bağlanır (varsayılan olarak 18789).
• Uzak kullanım için bu loopback portunu SSH üzerinden iletirsiniz (veya bir tailnet/VPN kullanıp daha az tünel kullanırsınız).

​

Yaygın VPN/tailnet kurulumları (ajanın bulunduğu yer)

​

1) Tailnet’inizde her zaman açık bir Gateway (VPS veya ev sunucusu)

• En iyi UX: gateway.bind: "loopback" olarak bırakın ve Kontrol UI için Tailscale Serve kullanın.
• Geri dönüş: loopback’i koruyun + erişim gerektiren her makineden SSH tüneli açın.
• Örnekler: exe.dev (kolay VM) veya Hetzner (üretim VPS’i).

​

2) Evdeki masaüstü Gateway’i çalıştırır, dizüstü uzaktan kontrol eder

• macOS uygulamasının Remote over SSH modunu kullanın (Ayarlar → Genel → “OpenClaw runs”).
• Uygulama tüneli açar ve yönetir, böylece WebChat + sağlık denetimleri “sorunsuzca” çalışır.

​

3) Dizüstü bilgisayar Gateway’i çalıştırır, diğer makinelerden uzaktan erişim sağlanır

• Diğer makinelerden dizüstüye SSH tüneli açın veya
• Tailscale Serve ile Kontrol UI’ı açığa çıkarın ve Gateway’i yalnızca loopback üzerinde tutun.

​

Komut akışı (ne nerede çalışır)

• Telegram mesajı Gateway’e gelir.
• Gateway ajanı çalıştırır ve bir düğüm aracı çağırıp çağırmayacağına karar verir.
• Gateway, Gateway WebSocket üzerinden düğümü çağırır (node.* RPC).
• Düğüm sonucu döndürür; Gateway de yanıtı Telegram’a geri yollar.

• Düğümler gateway hizmetini çalıştırmaz. Bilerek yalıtılmış profiller çalıştırmadığınız sürece host başına yalnızca bir gateway çalışmalıdır (bkz. Multiple gateways).
• macOS uygulaması “node mode”, Gateway WebSocket üzerinden çalışan bir düğüm istemcisinden ibarettir.

​

SSH tüneli (CLI + araçlar)

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

• openclaw health ve openclaw status --deep artık ws://127.0.0.1:18789 üzerinden uzak gateway’e ulaşır.
• openclaw gateway status, openclaw gateway health, openclaw gateway probe ve openclaw gateway call da gerektiğinde iletilen URL’yi --url ile hedefleyebilir.

​

CLI uzak varsayılanları

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

​

Kimlik bilgisi önceliği

• Açık kimlik bilgileri (--token, --password veya araç gatewayToken) açık kimlik doğrulama kabul eden çağrı yollarında her zaman önceliklidir.
• URL geçersiz kılma güvenliği:
  • CLI URL geçersiz kılmaları (--url) hiçbir zaman örtük yapılandırma/ortam kimlik bilgilerini yeniden kullanmaz.
  • Ortam URL geçersiz kılmaları (OPENCLAW_GATEWAY_URL) yalnızca ortam kimlik bilgilerini kullanabilir (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Yerel mod varsayılanları:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (uzak geri dönüş yalnızca yerel kimlik doğrulama token girdisi ayarlanmamışsa uygulanır)
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (uzak geri dönüş yalnızca yerel kimlik doğrulama parola girdisi ayarlanmamışsa uygulanır)
• Uzak mod varsayılanları:
  • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Node-host yerel mod istisnası: gateway.remote.token / gateway.remote.password yok sayılır.
• Uzak probe/status token denetimleri varsayılan olarak katıdır: uzak modu hedeflerken yalnızca gateway.remote.token kullanırlar (yerel token geri dönüşü yoktur).
• Gateway ortam geçersiz kılmaları yalnızca OPENCLAW_GATEWAY_* kullanır.

​

SSH üzerinden Chat UI

• SSH üzerinden 18789 portunu iletin (yukarıya bakın), ardından istemcileri ws://127.0.0.1:18789 adresine bağlayın.
• macOS’ta, tüneli otomatik yöneten uygulamanın “Remote over SSH” modunu tercih edin.

​

macOS uygulamasında “Remote over SSH”

​

Güvenlik kuralları (uzak/VPN)

• Loopback + SSH/Tailscale Serve en güvenli varsayılandır (genel açığa çıkma yok).
• Düz metin ws:// varsayılan olarak yalnızca loopback içindir. Güvenilen özel ağlar için istemci sürecinde OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 değerini camı kır seçeneği olarak ayarlayın.
• Loopback olmayan bağlamalar (lan/tailnet/custom veya loopback kullanılamadığında auto) gateway kimlik doğrulaması kullanmalıdır: token, parola veya gateway.auth.mode: "trusted-proxy" ile kimlik farkında ters proxy.
• gateway.remote.token / .password istemci kimlik bilgisi kaynaklarıdır. Sunucu kimlik doğrulamasını kendiliklerinden yapılandırmazlar.
• Yerel çağrı yolları, yalnızca gateway.auth.* ayarlanmamışsa gateway.remote.* değerlerini geri dönüş olarak kullanabilir.
• gateway.auth.token / gateway.auth.password, SecretRef ile açıkça yapılandırılmış ancak çözümlenmemişse, çözümleme güvenli biçimde kapanır (uzak geri dönüş bunu maskeleyemez).
• gateway.remote.tlsFingerprint, wss:// kullanılırken uzak TLS sertifikasını sabitler.
• Tailscale Serve, gateway.auth.allowTailscale: true olduğunda Kontrol UI/WebSocket trafiğini kimlik başlıklarıyla doğrulayabilir; HTTP API uç noktaları bu Tailscale başlık kimlik doğrulamasını kullanmaz ve bunun yerine gateway’in normal HTTP kimlik doğrulama modunu izler. Bu tokensiz akış, gateway host’una güvenildiğini varsayar. Her yerde paylaşılan gizli anahtar kimlik doğrulaması istiyorsanız bunu false yapın.
• Trusted-proxy kimlik doğrulaması yalnızca loopback olmayan, kimlik farkında proxy kurulumları içindir. Aynı host üzerindeki loopback ters proxy’ler gateway.auth.mode: "trusted-proxy" koşulunu sağlamaz.
• Tarayıcı denetimini operatör erişimi gibi değerlendirin: yalnızca tailnet + bilinçli düğüm eşleştirmesi.

​

macOS: LaunchAgent ile kalıcı SSH tüneli

​

1. adım: SSH yapılandırması ekleyin

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

​

2. adım: SSH anahtarını kopyalayın (bir kez)

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

​

3. adım: gateway token’ını yapılandırın

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

​

4. adım: LaunchAgent’i oluşturun

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

​

5. adım: LaunchAgent’i yükleyin

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

​

Sorun giderme

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