Chạy OpenClaw.app với Remote Gateway

OpenClaw.app sử dụng SSH tunneling để kết nối với remote gateway. Hướng dẫn này sẽ chỉ các bạn cách thiết lập.

Tổng quan

┌─────────────────────────────────────────────────────────────┐
│                        Client Machine                          │
│                                                              │
│  OpenClaw.app ──► ws://127.0.0.1:18789 (local port)           │
│                     │                                        │
│                     ▼                                        │
│  SSH Tunnel ────────────────────────────────────────────────│
│                     │                                        │
└─────────────────────┼──────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                         Remote Machine                        │
│                                                              │
│  Gateway WebSocket ──► ws://127.0.0.1:18789 ──►              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Thiết lập nhanh

Bước 1: Thêm SSH Config

Mở file ~/.ssh/config và thêm vào:

Host remote-gateway
    HostName <REMOTE_IP>          # ví dụ: 172.27.187.184
    User <REMOTE_USER>            # ví dụ: jefferson
    LocalForward 18789 127.0.0.1:18789
    IdentityFile ~/.ssh/id_rsa

Thay <REMOTE_IP> và <REMOTE_USER> bằng giá trị của các bạn.

Bước 2: Copy SSH Key

Copy public key của các bạn sang remote machine (nhập password một lần):

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

Bước 3: Đặt Gateway Token

launchctl setenv OPENCLAW_GATEWAY_TOKEN "<your-token>"

Bước 4: Khởi động SSH Tunnel

ssh -N remote-gateway &

Bước 5: Khởi động lại OpenClaw.app

# Thoát OpenClaw.app (⌘Q), sau đó mở lại:
open /path/to/OpenClaw.app

Ứng dụng giờ sẽ kết nối với remote gateway thông qua SSH tunnel.

Tự động khởi động Tunnel khi đăng nhập

Để SSH tunnel tự động khởi động khi các bạn đăng nhập, hãy tạo một Launch Agent.

Tạo file PLIST

Lưu nội dung này vào ~/Library/LaunchAgents/bot.molt.ssh-tunnel.plist:

<?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>bot.molt.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>

Load Launch Agent

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/bot.molt.ssh-tunnel.plist

Tunnel giờ sẽ:

Tự động khởi động khi các bạn đăng nhập
Tự động khởi động lại nếu bị crash
Chạy ngầm ở background

Lưu ý: xóa bỏ LaunchAgent com.openclaw.ssh-tunnel cũ nếu còn tồn tại.

Troubleshooting

Kiểm tra tunnel có đang chạy không:

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

Khởi động lại tunnel:

launchctl kickstart -k gui/$UID/bot.molt.ssh-tunnel

Dừng tunnel:

launchctl bootout gui/$UID/bot.molt.ssh-tunnel

Cách hoạt động

Component	Chức năng
`LocalForward 18789 127.0.0.1:18789`	Chuyển tiếp local port 18789 sang remote port 18789
`ssh -N`	SSH không thực thi lệnh từ xa (chỉ chuyển tiếp port)
`KeepAlive`	Tự động khởi động lại tunnel nếu bị crash
`RunAtLoad`	Khởi động tunnel khi agent được load

OpenClaw.app kết nối tới ws://127.0.0.1:18789 trên client machine của các bạn. SSH tunnel chuyển tiếp kết nối đó tới port 18789 trên remote machine nơi Gateway đang chạy.