> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

# الوصول عن بُعد (SSH، الأنفاق، وشبكات tailnet)

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

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

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

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

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

فكّر في **مضيف Gateway** على أنه «المكان الذي يعيش فيه الوكيل». فهو يملك الجلسات، وملفات المصادقة، والقنوات، والحالة.
يتصل حاسوبك المحمول/المكتبي (والعُقد) بذلك المضيف.

### 1. Gateway يعمل دائمًا داخل tailnet (خادم VPS أو خادم منزلي)

شغّل Gateway على مضيف دائم الوصول إليه عبر **Tailscale** أو SSH.

* **أفضل تجربة استخدام:** احتفِظ بـ `gateway.bind: "loopback"` واستخدم **Tailscale Serve** لواجهة التحكم.
* **خيار احتياطي:** احتفِظ بـ loopback + نفق SSH من أي جهاز يحتاج الوصول.
* **أمثلة:** [exe.dev](/install/exe-dev) (آلة افتراضية سهلة) أو [Hetzner](/install/hetzner) (VPS للإنتاج).

هذا مثالي عندما ينام حاسوبك المحمول كثيرًا لكنك تريد الوكيل يعمل دائمًا.

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

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

* استخدم وضع **Remote over SSH** في تطبيق macOS (الإعدادات → عام → «OpenClaw runs»).
* يفتح التطبيق النفق ويديره، لذا تعمل WebChat وفحوصات السلامة «بسلاسة».

دليل التشغيل: [الوصول عن بُعد على macOS](/platforms/mac/remote).

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

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

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

الدليل: [Tailscale](/gateway/tailscale) و[نظرة عامة على الويب](/web).

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

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

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

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

ملاحظات:

* **العُقد لا تُشغّل خدمة Gateway.** يجب تشغيل Gateway واحد فقط لكل مضيف ما لم تُشغّل عمدًا ملفات معزولة (انظر [Gateways متعددة](/gateway/multiple-gateways)).
* وضع «العُقدة» في تطبيق macOS هو مجرد عميل عُقدة عبر Gateway WebSocket.

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

أنشئ نفقًا محليًا إلى Gateway WS البعيد:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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,health,send,agent,call}` أيضًا استهداف عنوان URL المُعاد توجيهه عبر `--url` عند الحاجة.

ملاحظة: استبدل `18789` بما ضبطته من `gateway.port` (أو `--port`/`OPENCLAW_GATEWAY_PORT`).
ملاحظة: عند تمرير `--url`، لا يعود CLI إلى بيانات الاعتماد من التهيئة أو متغيرات البيئة.
ضمّن `--token` أو `--password` صراحةً. إن غابت بيانات الاعتماد الصريحة فهذا خطأ.

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}
```

عندما يكون Gateway مقتصرًا على loopback، أبقِ عنوان URL على `ws://127.0.0.1:18789` وافتح نفق SSH أولًا.

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

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

* أعد توجيه `18789` عبر SSH (انظر أعلاه)، ثم اربط العملاء بـ `ws://127.0.0.1:18789`.
* على macOS، يُفضّل وضع «Remote over SSH» في التطبيق، إذ يدير النفق تلقائيًا.

## تطبيق macOS «Remote over SSH»

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

دليل التشغيل: [الوصول عن بُعد على macOS](/platforms/mac/remote).

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

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

* **Loopback + SSH/Tailscale Serve** هو الإعداد الافتراضي الأكثر أمانًا (لا تعريض عام).
* **الروابط غير المعتمدة على loopback** (`lan`/`tailnet`/`custom`، أو `auto` عندما يتعذّر loopback) يجب أن تستخدم رموز مصادقة/كلمات مرور.
* `gateway.remote.token` مخصّص **فقط** لاستدعاءات CLI عن بُعد — ولا يفعّل المصادقة المحلية.
* `gateway.remote.tlsFingerprint` يثبّت شهادة TLS البعيدة عند استخدام `wss://`.
* يمكن لـ **Tailscale Serve** المصادقة عبر رؤوس الهوية عندما `gateway.auth.allowTailscale: true`.
  اضبطه على `false` إذا أردت استخدام الرموز/كلمات المرور بدلًا من ذلك.
* عامِل التحكم عبر المتصفح كصلاحية مشغّل: tailnet فقط + إقران عُقد متعمّد.

تعمّق أكثر: [الأمان](/gateway/security).