الوصول عن بُعد

يدعم هذا المستودع "الوصول البعيد عبر SSH" عبر إبقاء Gateway واحد (الرئيسي) يعمل على مضيف مخصص (سطح مكتب/خادم) وتوصيل العملاء به.

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

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

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

# إعدادات VPN والشبكات الخاصة الشائعة

فكّر في مضيف Gateway بوصفه المكان الذي يعيش فيه الوكيل. فهو يملك الجلسات، وملفات تعريف المصادقة، والقنوات، والحالة. يتصل حاسوبك المحمول، وسطح المكتب، والعُقد بذلك المضيف.

# Gateway دائم التشغيل في شبكتك الخاصة

شغّل Gateway على مضيف دائم (VPS أو خادم منزلي) وصِل إليه عبر Tailscale أو SSH.

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

مثالي عندما يدخل حاسوبك المحمول في وضع السكون كثيرًا لكنك تريد الوكيل دائم التشغيل.

# سطح المكتب المنزلي يشغّل Gateway

الحاسوب المحمول لا يشغّل الوكيل. بل يتصل عن بُعد:

• استخدم وضع الوصول البعيد عبر SSH في تطبيق macOS (الإعدادات → عام → تشغيل OpenClaw).
• يفتح التطبيق النفق ويديره، لذلك تعمل WebChat وفحوصات السلامة مباشرة.

دليل التشغيل: الوصول البعيد على macOS.

# الحاسوب المحمول يشغّل Gateway

أبقِ Gateway محليًا لكن اكشفه بأمان:

• نفق SSH إلى الحاسوب المحمول من أجهزة أخرى، أو
• استخدم Tailscale Serve لواجهة التحكم وأبقِ Gateway مقتصرًا على local loopback فقط.

الأدلة: Tailscale ونظرة عامة على الويب.

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

تمتلك خدمة Gateway واحدة الحالة + القنوات. العُقد ملحقات طرفية.

مثال تدفق (Telegram → عقدة):

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

ملاحظات:

• العُقد لا تشغّل خدمة Gateway. يجب تشغيل Gateway واحد فقط لكل مضيف إلا إذا كنت تشغّل عمدًا ملفات تعريف معزولة (راجع بوابات متعددة).
• "وضع العقدة" في تطبيق macOS هو مجرد عميل عقدة عبر مقبس الويب الخاص بـ Gateway.

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

أنشئ نفقًا محليًا إلى مقبس الويب الخاص بـ Gateway البعيد:

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

يمكنك حفظ هدف بعيد بحيث تستخدمه أوامر CLI افتراضيًا:

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

عندما يكون Gateway مقتصرًا على local loopback فقط، أبقِ عنوان URL على ws://127.0.0.1:18789 وافتح نفق SSH أولًا. في نقل نفق SSH الخاص بتطبيق macOS، توضع أسماء مضيف Gateway المكتشفة في gateway.remote.sshTarget؛ ويبقى gateway.remote.url عنوان URL للنفق المحلي.

# أسبقية بيانات الاعتماد

يتبع حل بيانات اعتماد Gateway عقدًا مشتركًا واحدًا عبر مسارات الاستدعاء/الفحص/الحالة ومراقبة موافقة التنفيذ في Discord. يستخدم مضيف العقدة العقد الأساسي نفسه مع استثناء واحد في الوضع المحلي (يتجاهل عمدًا gateway.remote.*):

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

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

لم تعد WebChat تستخدم منفذ HTTP منفصلًا. تتصل واجهة دردشة SwiftUI مباشرة بمقبس الويب الخاص بـ Gateway.

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

# الوصول البعيد عبر SSH في تطبيق macOS

يمكن لتطبيق شريط القوائم على macOS تشغيل الإعداد نفسه من البداية إلى النهاية (فحوصات الحالة البعيدة، وWebChat، وتمرير Voice Wake).

دليل التشغيل: الوصول البعيد على macOS.

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

النسخة المختصرة: أبقِ Gateway مقتصرًا على local loopback فقط إلا إذا كنت متأكدًا من أنك تحتاج إلى ربط.

• local loopback + SSH/Tailscale Serve هو الإعداد الافتراضي الأكثر أمانًا (لا تعريض عام).
• يكون النص الصريح ws:// مقتصرًا على local loopback افتراضيًا. للشبكات الخاصة الموثوقة، عيّن OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 على عملية العميل بوصفه إجراء كسر زجاج. لا يوجد مكافئ في openclaw.json؛ يجب أن يكون هذا في بيئة العملية للعميل الذي ينشئ اتصال مقبس الويب.
• الارتباطات غير المقتصرة على local loopback (lan/tailnet/custom، أو auto عندما لا يتوفر local loopback) يجب أن تستخدم مصادقة Gateway: رمزًا مميزًا، أو كلمة مرور، أو وكيلاً عكسيًا واعيًا بالهوية مع 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 مصادقة حركة واجهة التحكم/مقبس الويب عبر رؤوس الهوية عندما تكون gateway.auth.allowTailscale: true؛ لا تستخدم نقاط نهاية HTTP API مصادقة رؤوس Tailscale تلك، بل تتبع وضع مصادقة HTTP العادي في Gateway. يفترض هذا التدفق بلا رمز مميز أن مضيف Gateway موثوق. عيّنه إلى false إذا كنت تريد مصادقة بسر مشترك في كل مكان.
• تتوقع مصادقة الوكيل الموثوق إعدادات وكيل غير مقتصرة على local loopback وواعية بالهوية افتراضيًا. تتطلب الوكلاء العكسيون عبر local loopback على المضيف نفسه ضبط gateway.auth.trustedProxy.allowLoopback = true صراحة.
• تعامل مع التحكم عبر المتصفح مثل وصول المشغّل: شبكة خاصة فقط + إقران عقد مقصود.

شرح معمق: الأمان.

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

بالنسبة إلى عملاء macOS المتصلين بـ Gateway بعيد، يستخدم أسهل إعداد دائم إدخال تكوين SSH باسم LocalForward بالإضافة إلى LaunchAgent لإبقاء النفق حيًا عبر عمليات إعادة التشغيل والانهيارات.

# الخطوة 1: إضافة تكوين 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> بقيمك.

# الخطوة 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

احفظ هذا باسم ~/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>

# الخطوة 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

إدخال التكوين	ما الذي يفعله
LocalForward 18789 127.0.0.1:18789	يمرّر المنفذ المحلي 18789 إلى المنفذ البعيد 18789
ssh -N	SSH دون تنفيذ أوامر بعيدة (تمرير المنافذ فقط)
KeepAlive	يعيد تشغيل النفق تلقائيًا إذا انهار
RunAtLoad	يبدأ النفق عند تحميل LaunchAgent أثناء تسجيل الدخول

# ذات صلة

• Tailscale
• المصادقة
• إعداد Gateway بعيد