​

الوصول البعيد (SSH والأنفاق وtailnets)

• بالنسبة إلى المشغلين (أنت / تطبيق macOS): يكون نفق SSH هو الرجوع الاحتياطي العام.
• بالنسبة إلى العقد (iOS/Android والأجهزة المستقبلية): اتصل بـ WebSocket الخاصة بـ Gateway ‏(LAN/tailnet أو نفق SSH حسب الحاجة).

​

الفكرة الأساسية

• ترتبط Gateway WebSocket بعنوان loopback على المنفذ المكوّن لديك (الافتراضي 18789).
• للاستخدام البعيد، تقوم بتمرير منفذ loopback هذا عبر SSH (أو تستخدم tailnet/VPN وتقلل الحاجة إلى الأنفاق).

​

إعدادات VPN/tailnet الشائعة (حيث يعيش الوكيل)

​

1) Gateway دائمة التشغيل في tailnet الخاصة بك (VPS أو خادم منزلي)

• أفضل تجربة استخدام: أبقِ gateway.bind: "loopback" واستخدم Tailscale Serve لـ Control UI.
• الرجوع الاحتياطي: أبقِ loopback + نفق SSH من أي جهاز يحتاج إلى الوصول.
• أمثلة: exe.dev (VM سهلة) أو Hetzner (VPS للإنتاج).

​

2) سطح المكتب المنزلي يشغّل Gateway، والحاسوب المحمول هو جهاز التحكم البعيد

• استخدم وضع Remote over SSH في تطبيق macOS ‏(Settings → General → “OpenClaw runs”).
• يفتح التطبيق النفق ويديره، لذلك يعمل WebChat + فحوصات الصحة “فقط”.

​

3) الحاسوب المحمول يشغّل Gateway، مع وصول بعيد من أجهزة أخرى

• نفق SSH إلى الحاسوب المحمول من أجهزة أخرى، أو
• Tailscale Serve لـ Control UI مع إبقاء Gateway مقتصرة على loopback.

​

تدفق الأوامر (ما الذي يعمل وأين)

• تصل رسالة Telegram إلى Gateway.
• تشغّل Gateway الوكيل وتقرر ما إذا كانت ستستدعي أداة عقدة.
• تستدعي Gateway العقدة عبر Gateway WebSocket ‏(node.* RPC).
• تعيد العقدة النتيجة؛ ثم ترد Gateway مرة أخرى إلى Telegram.

• العقد لا تشغّل خدمة gateway. يجب أن تعمل gateway واحدة فقط لكل مضيف ما لم تكن تشغّل ملفات تعريف معزولة عمدًا (راجع Gateways متعددة).
• “وضع العقدة” في تطبيق macOS ليس إلا عميل عقدة عبر Gateway WebSocket.

​

نفق SSH ‏(CLI + الأدوات)

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

• سيصل openclaw health وopenclaw status --deep الآن إلى gateway البعيدة عبر ws://127.0.0.1:18789.
• يمكن أيضًا لـ openclaw gateway status وopenclaw gateway health وopenclaw gateway probe وopenclaw gateway call استهداف عنوان URL المُمرَّر عبر --url عند الحاجة.

​

الإعدادات الافتراضية البعيدة لـ CLI

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

​

أولوية بيانات الاعتماد

• تنتصر دائمًا بيانات الاعتماد الصريحة (--token أو --password أو أداة gatewayToken) في مسارات الاستدعاء التي تقبل مصادقة صريحة.
• أمان تجاوز عنوان URL:
  • لا تعيد تجاوزات CLI لعنوان URL ‏(--url) استخدام بيانات اعتماد ضمنية من التكوين/البيئة أبدًا.
  • قد تستخدم تجاوزات عنوان URL من البيئة (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-host في الوضع المحلي: يتم تجاهل gateway.remote.token / gateway.remote.password.
• تكون فحوصات رموز probe/status البعيدة صارمة افتراضيًا: إذ تستخدم gateway.remote.token فقط (من دون رجوع إلى الرمز المحلي) عند استهداف الوضع البعيد.
• تستخدم تجاوزات بيئة Gateway المتغيرات OPENCLAW_GATEWAY_* فقط.

​

واجهة الدردشة عبر SSH

• مرّر المنفذ 18789 عبر SSH ‏(انظر أعلاه)، ثم صِل العملاء إلى ws://127.0.0.1:18789.
• على macOS، فضّل وضع “Remote over SSH” في التطبيق، لأنه يدير النفق تلقائيًا.

​

وضع “Remote over SSH” في تطبيق macOS

​

قواعد الأمان (البعيد/VPN)

• Loopback + SSH/Tailscale Serve هو الإعداد الافتراضي الأكثر أمانًا (من دون كشف عام).
• تكون ws:// النصية الصريحة مقتصرة على loopback افتراضيًا. وللشبكات الخاصة الموثوقة، اضبط OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 على عملية العميل كخيار كسر زجاج.
• الربط غير الخاص بـ loopback ‏(lan/tailnet/custom، أو auto عندما لا تكون loopback متاحة) يجب أن يستخدم مصادقة gateway: رمزًا مميزًا أو كلمة مرور أو reverse proxy واعيًا بالهوية مع gateway.auth.mode: "trusted-proxy".
• إن gateway.remote.token / .password هما مصدران لبيانات اعتماد العميل. وهما لا يكوّنان مصادقة الخادم بحد ذاتهما.
• يمكن لمسارات الاستدعاء المحلية استخدام gateway.remote.* كرجوع احتياطي فقط عندما يكون gateway.auth.* غير معيّن.
• إذا كان gateway.auth.token / gateway.auth.password مكوّنين صراحةً عبر SecretRef وغير محلولين، فإن الحل يفشل بشكل مغلق (من دون أن يخفي الرجوع الاحتياطي البعيد ذلك).
• يقوم gateway.remote.tlsFingerprint بتثبيت شهادة TLS البعيدة عند استخدام wss://.
• يمكن لـ Tailscale Serve مصادقة حركة Control UI/WebSocket عبر ترويسات الهوية عندما تكون gateway.auth.allowTailscale: true؛ أما نقاط نهاية HTTP API فلا تستخدم مصادقة ترويسات Tailscale هذه، بل تتبع وضع مصادقة HTTP العادي الخاص بـ gateway. ويفترض هذا التدفق من دون رمز مميز أن مضيف gateway موثوق. اضبطها على false إذا كنت تريد مصادقة بالسر المشترك في كل مكان.
• إن مصادقة Trusted-proxy مخصصة فقط لإعدادات proxy غير loopback والواعية بالهوية. أما reverse proxies المحلية على المضيف نفسه عبر loopback فلا تفي بـ gateway.auth.mode: "trusted-proxy".
• تعامل مع التحكم في المتصفح كأنه وصول مشغل: tailnet فقط + pairing مقصود للعقدة.

​

macOS: نفق SSH دائم عبر LaunchAgent

​

الخطوة 1: أضف إعداد SSH

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

​

الخطوة 2: انسخ مفتاح SSH ‏(مرة واحدة)

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

​

الخطوة 3: اضبط رمز gateway

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

​

الخطوة 4: أنشئ 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>

​

الخطوة 5: حمّل LaunchAgent

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

​

استكشاف الأخطاء وإصلاحها

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