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

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

​

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

​

خيارات البنية

​

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

1. تصل رسالة Telegram إلى Gateway.
2. يشغّل Gateway الوكيل، الذي يقرر ما إذا كان سيستدعي أداة عُقدة.
3. يستدعي Gateway العُقدة عبر WebSocket الخاص بـ Gateway (استدعاء RPC ‏node.invoke).
4. تعيد العُقدة النتيجة؛ ويرد Gateway على Telegram.

​

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

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

​

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

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

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

​

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

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

​

الوصول عن بُعد إلى واجهة الدردشة

• أعد توجيه 18789 عبر SSH (راجع أعلاه)، ثم صِل العملاء بـ ws://127.0.0.1:18789.
• للوضع المباشر عبر LAN أو شبكة Tailscale، صِل العملاء بعنوان ws:// الخاص المُعدّ أو بعنوان wss:// الآمن.
• على macOS، يدير الوضع البعيد للتطبيق وسيلة النقل المحددة تلقائيًا.

​

الوضع البعيد لتطبيق macOS

​

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

• يُعد 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.remote.* كخيار رجوع إلا عندما لا يكون gateway.auth.* معيّنًا.
• إذا ضُبط 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 صراحةً.
• تعامل مع التحكم عبر المتصفح مثل وصول المشغّل: قصره على شبكة Tailscale مع إقران متعمّد للعُقد.

​

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

​

ذو صلة

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