دسترسی از راه دور

OpenClaw یک Gateway (گره اصلی) را روی یک میزبان اجرا می‌کند و همهٔ کلاینت‌ها را به آن متصل می‌کند. Gateway مالک نشست‌ها، پروفایل‌های احراز هویت، کانال‌ها و وضعیت است؛ هر چیز دیگری یک کلاینت محسوب می‌شود.

• اپراتورها (شما یا برنامهٔ macOS): وقتی Gateway در دسترس باشد، WebSocket مستقیم از طریق LAN/Tailnet ساده‌ترین روش است؛ تونل‌سازی SSH راهکار جایگزین همگانی است.
• Nodeها (iOS/Android و دستگاه‌های دیگر): به WebSocket مربوط به Gateway متصل می‌شوند (از طریق LAN/tailnet یا تونل SSH).

ایدهٔ اصلی

WebSocket مربوط به Gateway به‌طور پیش‌فرض روی local loopback و در پورت 18789 (gateway.port) متصل می‌شود. برای استفادهٔ راه‌دور، آن را از طریق Tailscale Serve یا اتصال مطمئن LAN-Tailnet در دسترس قرار دهید، یا پورت local loopback را از طریق SSH فوروارد کنید.

گزینه‌های توپولوژی

برای راه‌اندازی‌های همیشه‌روشن و لپ‌تاپ، بهتر است gateway.bind: "loopback" را حفظ کنید و برای رابط کاربری کنترل از Tailscale Serve یا اتصال مطمئن LAN/Tailnet همراه با gateway.remote.transport: "direct" استفاده کنید. تونل SSH راهکار جایگزینی است که از هر ماشینی کار می‌کند.

جریان فرمان (هر بخش کجا اجرا می‌شود)

یک Gateway مالک وضعیت و کانال‌ها است؛ Nodeها تجهیزات جانبی هستند. نمونه (پیام Telegram که به ابزار یک Node هدایت می‌شود):

1. پیام Telegram به Gateway می‌رسد.
2. Gateway عامل را اجرا می‌کند و عامل تصمیم می‌گیرد که آیا ابزار یک Node را فراخوانی کند.
3. Gateway از طریق WebSocket مربوط به Gateway، Node را فراخوانی می‌کند (node.invoke RPC).
4. Node نتیجه را برمی‌گرداند؛ Gateway به Telegram پاسخ می‌دهد.

Nodeها سرویس Gateway را اجرا نمی‌کنند. در هر میزبان باید فقط یک Gateway اجرا شود، مگر اینکه عمداً پروفایل‌های مجزا اجرا کنید (چند Gateway را ببینید). «حالت Node» برنامهٔ macOS صرفاً یک کلاینت Node روی WebSocket مربوط به Gateway است.

تونل SSH ‏(CLI و ابزارها)

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

پس از برقراری تونل، openclaw health و openclaw status --deep از طریق ws://127.0.0.1:18789 به Gateway راه‌دور دسترسی پیدا می‌کنند. openclaw gateway status،‏ openclaw gateway health،‏ openclaw gateway probe و openclaw gateway call نیز می‌توانند با استفاده از --url یک نشانی فورواردشده را هدف قرار دهند.

پیش‌فرض‌های راه‌دور CLI

یک مقصد راه‌دور را ذخیره کنید تا فرمان‌های CLI به‌طور پیش‌فرض از آن استفاده کنند:

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

وقتی Gateway فقط روی local loopback قرار دارد، نشانی را روی ws://127.0.0.1:18789 نگه دارید و ابتدا تونل SSH را باز کنید. در انتقال تونل SSH برنامهٔ macOS، نام میزبان Gateway کشف‌شده در gateway.remote.sshTarget قرار می‌گیرد (user@host یا user@host:port)؛ gateway.remote.url همان نشانی تونل محلی باقی می‌ماند. اگر پورت راه‌دور با پورت محلی متفاوت است، gateway.remote.remotePort را تنظیم کنید.

اعتبارسنجی کلید میزبان به‌طور پیش‌فرض سخت‌گیرانه است (gateway.remote.sshHostKeyPolicy: "strict"). برای واگذاری آن به پیکربندی مؤثر OpenSSH خود، مقدار را روی "openssh" تنظیم کنید؛ پیش از فعال‌سازی، تنظیمات SSH کاربر و سیستم خود را بررسی کنید.

برای Gatewayای که از قبل در یک LAN یا Tailnet مطمئن در دسترس است، از حالت مستقیم استفاده کنید:

{  gateway: {    mode: "remote",    remote: {      transport: "direct",      url: "ws://192.168.0.202:18789",      token: "your-token",    },  },}

اولویت اطلاعات هویتی

تفکیک اطلاعات هویتی Gateway در مسیرهای فراخوانی/کاوش/وضعیت و پایش تأیید اجرای Discord از یک قرارداد مشترک پیروی می‌کند. میزبان Node نیز با یک استثنا در حالت محلی از همین قرارداد استفاده می‌کند (gateway.remote.* را نادیده می‌گیرد).

• اطلاعات هویتی صریح (--token،‏ --password یا gatewayToken یک ابزار) در مسیرهای فراخوانی که احراز هویت صریح را می‌پذیرند، همیشه اولویت دارند.
• ایمنی بازنویسی نشانی:
  • گزینهٔ --url در CLI هرگز از اطلاعات هویتی ضمنی پیکربندی/محیط استفاده نمی‌کند.
  • متغیر محیطی OPENCLAW_GATEWAY_URL فقط می‌تواند از اطلاعات هویتی محیطی استفاده کند (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• پیش‌فرض‌های حالت محلی:
  • توکن: OPENCLAW_GATEWAY_TOKEN ← gateway.auth.token ← gateway.remote.token (بازگشت به مقدار راه‌دور فقط وقتی توکن محلی تنظیم نشده باشد)
  • گذرواژه: OPENCLAW_GATEWAY_PASSWORD ← gateway.auth.password ← gateway.remote.password (بازگشت به مقدار راه‌دور فقط وقتی گذرواژهٔ محلی تنظیم نشده باشد)
• پیش‌فرض‌های حالت راه‌دور:
  • توکن: gateway.remote.token ← OPENCLAW_GATEWAY_TOKEN ← gateway.auth.token
  • گذرواژه: OPENCLAW_GATEWAY_PASSWORD ← gateway.remote.password ← gateway.auth.password
• استثنای حالت محلی میزبان Node:‏ gateway.remote.token / gateway.remote.password نادیده گرفته می‌شوند.
• بررسی‌های توکن کاوش/وضعیت راه‌دور به‌طور پیش‌فرض سخت‌گیرانه‌اند: هنگام هدف‌گیری حالت راه‌دور فقط از gateway.remote.token استفاده می‌کنند (بدون بازگشت به توکن محلی).
• بازنویسی‌های محیطی Gateway فقط از OPENCLAW_GATEWAY_* استفاده می‌کنند.

دسترسی راه‌دور به رابط کاربری گفت‌وگو

WebChat پورت HTTP جداگانه‌ای ندارد؛ رابط کاربری گفت‌وگوی SwiftUI مستقیماً به WebSocket مربوط به Gateway متصل می‌شود.

• پورت 18789 را از طریق SSH فوروارد کنید (بخش بالا را ببینید)، سپس کلاینت‌ها را به ws://127.0.0.1:18789 متصل کنید.
• برای حالت مستقیم LAN/Tailnet، کلاینت‌ها را به نشانی خصوصی پیکربندی‌شدهٔ ws:// یا نشانی امن wss:// متصل کنید.
• در macOS، حالت راه‌دور برنامه انتقال انتخاب‌شده را به‌طور خودکار مدیریت می‌کند.

حالت راه‌دور برنامهٔ macOS

برنامهٔ نوار منوی macOS همین راه‌اندازی را از ابتدا تا انتها مدیریت می‌کند: بررسی‌های وضعیت راه‌دور، WebChat و فورواردکردن Voice Wake. راهنمای اجرایی: دسترسی راه‌دور macOS.

قواعد امنیتی (راه‌دور/VPN)

Gateway را فقط روی local loopback نگه دارید، مگر اینکه مطمئن باشید به اتصال دیگری نیاز دارید.

• local loopback همراه با SSH/Tailscale Serve امن‌ترین حالت پیش‌فرض است (بدون قرارگیری در معرض دسترسی عمومی).
• ws:// بدون رمزنگاری برای local loopback، شبکهٔ خصوصی/LAN ‏(RFC 1918)، پیوند محلی، CGNAT و میزبان‌های .local و .ts.net پذیرفته می‌شود. میزبان‌های عمومی راه‌دور باید از wss:// استفاده کنند.
• اتصال‌های غیر-local loopback (lan/tailnet/custom یا auto وقتی local loopback در دسترس نیست) باید از احراز هویت Gateway استفاده کنند: توکن، گذرواژه یا پراکسی معکوس آگاه از هویت همراه با gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password منابع اطلاعات هویتی کلاینت هستند؛ این مقادیر به‌تنهایی احراز هویت سرور را پیکربندی نمی‌کنند.
• مسیرهای فراخوانی محلی فقط وقتی gateway.auth.* تنظیم نشده باشد می‌توانند از gateway.remote.* به‌عنوان مقدار جایگزین استفاده کنند.
• اگر gateway.auth.token / gateway.auth.password صریحاً از طریق SecretRef پیکربندی شده اما قابل تفکیک نباشد، فرایند به‌صورت بسته و ناموفق پایان می‌یابد (مقدار جایگزین راه‌دور خطا را پنهان نمی‌کند).
• gateway.remote.tlsFingerprint گواهی TLS راه‌دور را برای wss://، از جمله حالت مستقیم macOS، سنجاق می‌کند. بدون اثر انگشت ذخیره‌شده، macOS فقط پس از موفقیت اعتماد معمول سیستم، در نخستین استفاده آن را سنجاق می‌کند؛ Gatewayهای خودامضا یا دارای مرجع صدور گواهی خصوصی به اثر انگشت صریح یا اتصال راه‌دور از طریق SSH نیاز دارند.
• Tailscale Serve می‌تواند ترافیک رابط کاربری کنترل/WebSocket را با سرآیندهای هویتی احراز کند، مشروط بر اینکه gateway.auth.allowTailscale: true باشد. نقاط پایانی HTTP API از این احراز هویت مبتنی بر سرآیند استفاده نمی‌کنند و در عوض از حالت عادی احراز هویت HTTP مربوط به Gateway پیروی می‌کنند. این جریان بدون توکن فرض می‌کند میزبان Gateway قابل اعتماد است؛ برای استفاده از احراز هویت با راز مشترک در همه‌جا، آن را روی false تنظیم کنید.
• احراز هویت پراکسی مطمئن به‌طور پیش‌فرض انتظار یک پراکسی غیر-local loopback و آگاه از هویت را دارد. پراکسی‌های معکوس local loopback روی همان میزبان به gateway.auth.trustedProxy.allowLoopback = true صریح نیاز دارند.
• کنترل از طریق مرورگر را همانند دسترسی اپراتور در نظر بگیرید: فقط در tailnet و همراه با جفت‌سازی آگاهانهٔ Node.

بررسی عمیق: امنیت.

macOS: تونل دائمی SSH از طریق LaunchAgent

برای کلاینت‌های macOS، ساده‌ترین راه‌اندازی دائمی از یک ورودی پیکربندی SSH برای LocalForward به‌همراه یک LaunchAgent استفاده می‌کند که تونل را پس از راه‌اندازی مجدد و خرابی فعال نگه می‌دارد.

گام ۱: افزودن پیکربندی SSH

فایل ~/.ssh/config را ویرایش کنید:

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

<REMOTE_IP> و <REMOTE_USER> را با مقادیر خود جایگزین کنید.

گام ۲: کپی‌کردن کلید SSH (یک‌بار)

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

گام ۳: پیکربندی توکن Gateway

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

اگر Gateway راه‌دور از احراز هویت با گذرواژه استفاده می‌کند، به‌جای آن از gateway.remote.password استفاده کنید. OPENCLAW_GATEWAY_TOKEN همچنان به‌عنوان بازنویسی در سطح پوسته معتبر است، اما راه‌اندازی پایدار کلاینت راه‌دور gateway.remote.token / gateway.remote.password است.

گام ۴: ایجاد LaunchAgent

آن را با نام ~/Library/LaunchAgents/ai.openclaw.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>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>

گام ۵: بارگذاری LaunchAgent

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

تونل هنگام ورود به سیستم به‌طور خودکار آغاز می‌شود، پس از خرابی دوباره راه‌اندازی می‌شود و پورت فورواردشده را فعال نگه می‌دارد.

عیب‌یابی

# Check if the tunnel is runningps aux | grep "ssh -N remote-gateway" | grep -v greplsof -i :18789 # Restart the tunnellaunchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel # Stop the tunnellaunchctl bootout gui/$UID/ai.openclaw.ssh-tunnel

مطالب مرتبط

• Tailscale
• احراز هویت
• راه‌اندازی Gateway راه‌دور