--- read_when: - تريد دفاعًا متعدد الطبقات ضد هجمات SSRF وإعادة ربط DNS - تكوين وكيل أمامي خارجي لحركة مرور وقت تشغيل OpenClaw summary: كيفية توجيه حركة مرور HTTP وWebSocket وقت تشغيل OpenClaw عبر وكيل تصفية يديره المشغّل title: وكيل الشبكة x-i18n: generated_at: "2026-05-07T16:23:54Z" model: gpt-5.5 provider: openai source_hash: 22895b7c5521927b7145f55dff9b777e701691f01a6421db0f5b1ff489734775 source_path: security/network-proxy.md workflow: 16 --- يمكن لـ OpenClaw توجيه حركة مرور HTTP وWebSocket وقت التشغيل عبر وكيل توجيه مُدار من المشغّل. هذا دفاع اختياري متعدد الطبقات لعمليات النشر التي تريد تحكمًا مركزيًا في الخروج، وحماية أقوى من SSRF، وقابلية تدقيق أفضل للشبكة. لا يوفّر OpenClaw وكيلاً ولا ينزّله ولا يشغّله ولا يهيئه ولا يصادقه. أنت تشغّل تقنية الوكيل التي تناسب بيئتك، ويوجّه OpenClaw عملاء HTTP وWebSocket المحليين للعملية عبره. ## لماذا تستخدم وكيلاً يمنح الوكيل المشغّلين نقطة تحكم شبكية واحدة لحركة مرور HTTP وWebSocket الصادرة. قد يكون ذلك مفيدًا حتى خارج تعزيز الحماية من SSRF: - سياسة مركزية: حافظ على سياسة خروج واحدة بدلاً من الاعتماد على كل موضع استدعاء HTTP في التطبيق لضبط قواعد الشبكة بشكل صحيح. - فحوصات وقت الاتصال: قيّم الوجهة بعد حل DNS ومباشرة قبل أن يفتح الوكيل اتصال المنبع. - دفاع ضد إعادة ربط DNS: قلّل الفجوة بين فحص DNS على مستوى التطبيق والاتصال الصادر الفعلي. - تغطية JavaScript أوسع: وجّه عملاء `fetch` و`node:http` و`node:https` وWebSocket وaxios وgot وnode-fetch والعملاء المشابهين عبر المسار نفسه. - قابلية التدقيق: سجّل الوجهات المسموح بها والمرفوضة عند حد الخروج. - تحكم تشغيلي: افرض قواعد الوجهات أو تجزئة الشبكة أو حدود المعدلات أو قوائم السماح الصادرة دون إعادة بناء OpenClaw. توجيه الوكيل حاجز حماية على مستوى العملية لخروج HTTP وWebSocket العادي. يمنح المشغّلين مسارًا يفشل مغلقًا لتوجيه عملاء HTTP في JavaScript المدعومين عبر وكيل الترشيح الخاص بهم، لكنه ليس صندوق حماية شبكيًا على مستوى نظام التشغيل ولا يجعل OpenClaw يصادق سياسة وجهات الوكيل. ## كيف يوجّه OpenClaw حركة المرور عندما تكون `proxy.enabled=true` ويكون عنوان URL للوكيل مهيئًا، توجّه عمليات وقت التشغيل المحمية مثل `openclaw gateway run` و`openclaw node run` و`openclaw agent --local` خروج HTTP وWebSocket العادي عبر الوكيل المهيأ: ```text OpenClaw process fetch -> operator-managed filtering proxy -> public internet node:http and https -> operator-managed filtering proxy -> public internet WebSocket clients -> operator-managed filtering proxy -> public internet ``` العقد العام هو سلوك التوجيه، وليس خطافات Node الداخلية المستخدمة لتنفيذه. يستخدم عملاء WebSocket في مستوى تحكم OpenClaw Gateway مسارًا مباشرًا ضيقًا لحركة RPC الخاصة بـ Gateway عبر local loopback عندما يستخدم عنوان URL الخاص بـ Gateway `localhost` أو عنوان IP حلقة رجوع حرفيًا مثل `127.0.0.1` أو `[::1]`. يجب أن يتمكن مسار مستوى التحكم هذا من الوصول إلى Gateways عبر حلقة الرجوع حتى عندما يحظر وكيل المشغّل وجهات حلقة الرجوع. لا تزال طلبات HTTP وWebSocket العادية في وقت التشغيل تستخدم الوكيل المهيأ. داخليًا، يستخدم OpenClaw خطافي توجيه على مستوى العملية لهذه الميزة: - يغطي توجيه موزّع Undici `fetch` والعملاء المستندين إلى undici ووسائل النقل التي توفر موزّع undici خاصًا بها. - يغطي توجيه `global-agent` مستدعي Node الأساسيين `node:http` و`node:https`، بما في ذلك كثير من المكتبات المبنية على `http.request` و`https.request` و`http.get` و`https.get`. يفرض وضع الوكيل المُدار ذلك العامل العام حتى لا تتجاوز عوامل HTTP الصريحة في Node وكيل المشغّل عن طريق الخطأ. تملك بعض Plugins وسائل نقل مخصصة تحتاج إلى توصيل صريح بالوكيل حتى عند وجود توجيه على مستوى العملية. على سبيل المثال، تستخدم وسيلة نقل Bot API الخاصة بـ Telegram موزّع undici خاصًا بها لـ HTTP/1، ولذلك تحترم بيئة وكيل العملية بالإضافة إلى fallback المُدار `OPENCLAW_PROXY_URL` في مسار النقل الخاص بذلك المالك. يجب أن يستخدم عنوان URL للوكيل نفسه `http://`. لا تزال وجهات HTTPS مدعومة عبر الوكيل باستخدام HTTP `CONNECT`؛ وهذا يعني فقط أن OpenClaw يتوقع مستمع وكيل توجيه HTTP عاديًا مثل `http://127.0.0.1:3128`. أثناء نشاط الوكيل، يمسح OpenClaw القيم `no_proxy` و`NO_PROXY` و`GLOBAL_AGENT_NO_PROXY`. قوائم التجاوز هذه مبنية على الوجهة، لذلك فإن ترك `localhost` أو `127.0.0.1` فيها سيتيح لأهداف SSRF عالية الخطورة تخطي وكيل الترشيح. عند إيقاف التشغيل، يستعيد OpenClaw بيئة الوكيل السابقة ويعيد ضبط حالة توجيه العملية المخزنة مؤقتًا. ## مصطلحات الوكيل ذات الصلة - `proxy.enabled` / `proxy.proxyUrl`: توجيه وكيل التوجيه الصادر لخروج وقت تشغيل OpenClaw. توثّق هذه الصفحة هذه الميزة. - `gateway.auth.mode: "trusted-proxy"`: مصادقة وكيل عكسي واردة واعية بالهوية للوصول إلى Gateway. راجع [مصادقة الوكيل الموثوق](/ar/gateway/trusted-proxy-auth). - `openclaw proxy`: وكيل تصحيح محلي ومفتش التقاط للتطوير والدعم. راجع [openclaw proxy](/ar/cli/proxy). - `tools.web.fetch.useTrustedEnvProxy`: اشتراك اختياري لـ `web_fetch` للسماح لوكيل بيئة HTTP(S) يتحكم به المشغّل بحل DNS مع الحفاظ على التثبيت الصارم الافتراضي لـ DNS وسياسة أسماء المضيفين. راجع [جلب الويب](/ar/tools/web-fetch#trusted-env-proxy). - إعدادات الوكيل الخاصة بالقناة أو المزوّد: تجاوزات خاصة بالمالك لوسيلة نقل معينة. فضّل وكيل الشبكة المُدار عندما يكون الهدف هو التحكم المركزي في الخروج عبر وقت التشغيل. ## التهيئة ```yaml proxy: enabled: true proxyUrl: http://127.0.0.1:3128 ``` يمكنك أيضًا توفير عنوان URL عبر البيئة، مع إبقاء `proxy.enabled=true` في التهيئة: ```bash OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run ``` تكون الأولوية لـ `proxy.proxyUrl` على `OPENCLAW_PROXY_URL`. ### وضع حلقة رجوع Gateway يتصل عملاء مستوى التحكم المحليون في Gateway عادةً بـ WebSocket حلقة رجوع مثل `ws://127.0.0.1:18789`. استخدم `proxy.loopbackMode` لاختيار سلوك حركة المرور هذه أثناء نشاط الوكيل المُدار: ```yaml proxy: enabled: true proxyUrl: http://127.0.0.1:3128 loopbackMode: gateway-only # gateway-only, proxy, or block ``` - `gateway-only` (الافتراضي): يسجّل OpenClaw سلطة حلقة رجوع Gateway في وحدة تحكم `NO_PROXY` النشطة الخاصة بـ `global-agent` حتى تتمكن حركة WebSocket المحلية الخاصة بـ Gateway من الاتصال مباشرة. تعمل منافذ Gateway المخصصة عبر حلقة الرجوع لأن مضيف ومنفذ عنوان URL النشط لـ Gateway مسجلان. - `proxy`: لا يسجّل OpenClaw سلطة `NO_PROXY` لحلقة رجوع Gateway، لذلك تُرسل حركة Gateway المحلية عبر الوكيل المُدار. إذا كان الوكيل بعيدًا، فيجب أن يوفر توجيهًا خاصًا لخدمة حلقة الرجوع الخاصة بمضيف OpenClaw، مثل ربطها باسم مضيف أو IP أو نفق يمكن للوكيل الوصول إليه. تحل الوكلاء البعيدة القياسية `127.0.0.1` و`localhost` من مضيف الوكيل، وليس من مضيف OpenClaw. - `block`: يرفض OpenClaw اتصالات مستوى التحكم الخاصة بـ Gateway عبر حلقة الرجوع قبل فتح مقبس. إذا كانت `enabled=true` لكن لم تتم تهيئة عنوان URL صالح للوكيل، تفشل الأوامر المحمية عند بدء التشغيل بدلاً من الرجوع إلى الوصول المباشر إلى الشبكة. لخدمات Gateway المُدارة التي تبدأ باستخدام `openclaw gateway start`، فضّل تخزين عنوان URL في التهيئة: ```bash openclaw config set proxy.enabled true openclaw config set proxy.proxyUrl http://127.0.0.1:3128 openclaw gateway install --force openclaw gateway start ``` يكون fallback البيئي أفضل للتشغيل في المقدمة. إذا استخدمته مع خدمة مثبتة، فضع `OPENCLAW_PROXY_URL` في بيئة الخدمة الدائمة، مثل `$OPENCLAW_STATE_DIR/.env` أو `~/.openclaw/.env`، ثم أعد تثبيت الخدمة حتى يبدأ launchd أو systemd أو Scheduled Tasks تشغيل Gateway بهذه القيمة. بالنسبة إلى أوامر `openclaw --container ...`، يمرر OpenClaw `OPENCLAW_PROXY_URL` إلى CLI الابن المستهدف للحاوية عند تعيينه. يجب أن يكون عنوان URL قابلاً للوصول من داخل الحاوية؛ يشير `127.0.0.1` إلى الحاوية نفسها، وليس إلى المضيف. يرفض OpenClaw عناوين URL لوكيل حلقة الرجوع للأوامر المستهدفة للحاويات ما لم تتجاوز فحص السلامة هذا صراحةً. ## متطلبات الوكيل سياسة الوكيل هي حد الأمان. لا يستطيع OpenClaw التحقق من أن الوكيل يحظر الأهداف الصحيحة. هيّئ الوكيل لكي: - يرتبط بحلقة الرجوع فقط أو بواجهة خاصة موثوقة. - يقيّد الوصول بحيث لا يستطيع استخدامه إلا عملية OpenClaw أو المضيف أو الحاوية أو حساب الخدمة. - يحل الوجهات بنفسه ويحظر عناوين IP للوجهات بعد حل DNS. - يطبّق السياسة وقت الاتصال لكل من طلبات HTTP العادية وأنفاق HTTPS `CONNECT`. - يرفض التجاوزات المبنية على الوجهة لحلقة الرجوع والنطاقات الخاصة والمحلية للرابط والبيانات الوصفية والبث المتعدد والمحجوزة أو نطاقات التوثيق. - يتجنب قوائم السماح بأسماء المضيفين ما لم تكن تثق تمامًا بمسار حل DNS. - يسجّل الوجهة والقرار والحالة والسبب دون تسجيل أجسام الطلبات أو ترويسات التفويض أو ملفات تعريف الارتباط أو الأسرار الأخرى. - يحتفظ بسياسة الوكيل تحت التحكم في الإصدارات ويراجع التغييرات مثل التهيئات الحساسة أمنيًا. ## الوجهات الموصى بحظرها استخدم قائمة الرفض هذه كنقطة بداية لأي وكيل توجيه أو جدار حماية أو سياسة خروج. توجد منطقية المصنّف على مستوى تطبيق OpenClaw في `src/infra/net/ssrf.ts` و`src/shared/net/ip.ts`. خطافات التكافؤ ذات الصلة هي `BLOCKED_HOSTNAMES` و`BLOCKED_IPV4_SPECIAL_USE_RANGES` و`BLOCKED_IPV6_SPECIAL_USE_RANGES` و`RFC2544_BENCHMARK_PREFIX` ومعالجة حارس IPv4 المضمّن لـ NAT64 و6to4 وTeredo وISATAP والصيغ المعيّنة إلى IPv4. هذه الملفات مراجع مفيدة عند صيانة سياسة وكيل خارجية، لكن OpenClaw لا يصدّر هذه القواعد أو يفرضها تلقائيًا في وكيلك. | النطاق أو المضيف | سبب الحظر | | ------------------------------------------------------------------------------------ | ---------------------------------------------------- | | `127.0.0.0/8`, `localhost`, `localhost.localdomain` | حلقة رجوع IPv4 | | `::1/128` | حلقة رجوع IPv6 | | `0.0.0.0/8`, `::/128` | عناوين غير محددة وعناوين هذه الشبكة | | `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | شبكات RFC1918 الخاصة | | `169.254.0.0/16`, `fe80::/10` | عناوين محلية للرابط ومسارات شائعة لبيانات السحابة الوصفية | | `169.254.169.254`, `metadata.google.internal` | خدمات بيانات السحابة الوصفية | | `100.64.0.0/10` | مساحة عناوين مشتركة لـ NAT بدرجة شركات الاتصالات | | `198.18.0.0/15`, `2001:2::/48` | نطاقات قياس الأداء | | `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | نطاقات استخدام خاص وتوثيق | | `224.0.0.0/4`, `ff00::/8` | بث متعدد | | `240.0.0.0/4` | IPv4 محجوز | | `fc00::/7`, `fec0::/10` | نطاقات IPv6 محلية/خاصة | | `100::/64`, `2001:20::/28` | نطاقات تجاهل IPv6 وORCHIDv2 | | `64:ff9b::/96`, `64:ff9b:1::/48` | بادئات NAT64 مع IPv4 مضمن | | `2002::/16`, `2001::/32` | 6to4 وTeredo مع IPv4 مضمن | | `::/96`, `::ffff:0:0/96` | IPv6 متوافق مع IPv4 ومعيّن إلى IPv4 | إذا وثّق مزوّد السحابة أو منصة الشبكة لديك مضيفين إضافيين للبيانات الوصفية أو نطاقات محجوزة، فأضفها أيضًا. ## التحقق تحقق من الوكيل من المضيف أو الحاوية أو حساب الخدمة نفسه الذي يشغّل OpenClaw: ```bash openclaw proxy validate --proxy-url http://127.0.0.1:3128 ``` افتراضيًا، عند عدم توفير وجهات مخصّصة، يتحقق الأمر من نجاح `https://example.com/` ويبدأ كناريًا مؤقتًا لحلقة الرجوع يجب ألا يصل إليه الوكيل. ينجح فحص الرفض الافتراضي عندما يعيد الوكيل استجابة رفض غير 2xx أو يحظر الكناري بفشل نقل؛ ويفشل إذا وصلت استجابة ناجحة إلى الكناري. إذا لم يكن أي وكيل مفعّلًا ومُكوَّنًا، فسيبلّغ التحقق عن مشكلة في الإعدادات؛ استخدم `--proxy-url` لإجراء فحص تمهيدي لمرة واحدة قبل تغيير الإعدادات. استخدم `--allowed-url` و`--denied-url` لاختبار التوقعات الخاصة بالنشر. أضف `--apns-reachable` للتحقق أيضًا من أن تسليم APNs HTTP/2 المباشر يمكنه فتح نفق CONNECT عبر الوكيل وتلقي استجابة APNs من بيئة الحماية؛ يستخدم المسبار رمز موفّر غير صالح عمدًا، لذلك يكون `403 InvalidProviderToken` متوقعًا ويُحتسب كدليل على إمكانية الوصول. الوجهات المرفوضة المخصّصة تفشل مغلقة: أي استجابة HTTP تعني أن الوجهة كان يمكن الوصول إليها عبر الوكيل، وأي خطأ نقل يُبلّغ عنه على أنه غير حاسم لأن OpenClaw لا يمكنه إثبات أن الوكيل حظر أصلًا يمكن الوصول إليه. عند فشل التحقق، يخرج الأمر بالرمز 1. استخدم `--json` للأتمتة. يحتوي خرج JSON على النتيجة الإجمالية، ومصدر إعداد الوكيل الفعلي، وأي أخطاء إعداد، وكل فحص وجهة. تُحجب بيانات اعتماد عنوان URL للوكيل في خرج النص وJSON: ```json { "ok": true, "config": { "enabled": true, "proxyUrl": "http://127.0.0.1:3128/", "source": "override", "errors": [] }, "checks": [ { "kind": "allowed", "url": "https://example.com/", "ok": true, "status": 200 }, { "kind": "apns", "url": "https://api.sandbox.push.apple.com", "ok": true, "status": 403 } ] } ``` يمكنك أيضًا التحقق يدويًا باستخدام `curl`: ```bash curl -x http://127.0.0.1:3128 https://example.com/ curl -x http://127.0.0.1:3128 http://127.0.0.1/ curl -x http://127.0.0.1:3128 http://169.254.169.254/ ``` يجب أن ينجح الطلب العام. ويجب أن يحظر الوكيل طلبات حلقة الرجوع والبيانات الوصفية. بالنسبة إلى `openclaw proxy validate`، يستطيع كناري حلقة الرجوع المضمّن تمييز رفض الوكيل عن أصل يمكن الوصول إليه. لا تحتوي فحوصات `--denied-url` المخصّصة على ذلك الكناري، لذلك تعامل مع كل من استجابات HTTP وفشل النقل الغامض كإخفاقات تحقق ما لم يوفّر وكيلك إشارة رفض خاصة بالنشر يمكنك التحقق منها بشكل منفصل. ثم فعّل توجيه وكيل OpenClaw: ```bash openclaw config set proxy.enabled true openclaw config set proxy.proxyUrl http://127.0.0.1:3128 openclaw gateway run ``` أو عيّن: ```yaml proxy: enabled: true proxyUrl: http://127.0.0.1:3128 ``` ## الحدود - يحسّن الوكيل التغطية لعملاء JavaScript HTTP وWebSocket المحليين ضمن العملية، لكنه ليس صندوق حماية شبكيًا على مستوى نظام التشغيل. - يكون مرور مستوى تحكم حلقة رجوع Gateway افتراضيًا كتجاوز محلي مباشر عبر `proxy.loopbackMode: "gateway-only"`. ينفّذ OpenClaw هذا التجاوز عن طريق تسجيل سلطة حلقة رجوع Gateway النشطة في متحكم `global-agent` `NO_PROXY` المُدار. يمكن للمشغلين تعيين `proxy.loopbackMode: "proxy"` لإرسال مرور حلقة رجوع Gateway عبر الوكيل المُدار، أو `proxy.loopbackMode: "block"` لرفض اتصالات Gateway عبر حلقة الرجوع. راجع [وضع حلقة رجوع Gateway](#gateway-loopback-mode) لمعرفة التحذير المتعلق بالوكيل البعيد. - قد تتجاوز مقابس `net` و`tls` و`http2` الخام، والإضافات الأصلية، وعمليات الأبناء غير التابعة لـ OpenClaw توجيه الوكيل على مستوى Node ما لم ترث متغيرات بيئة الوكيل وتحترمها. ترث واجهات CLI التابعة لـ OpenClaw المتفرعة عنوان URL للوكيل المُدار وحالة `proxy.loopbackMode`. - IRC قناة TCP/TLS خام خارج توجيه وكيل التمرير الأمامي المُدار بواسطة المشغّل. في عمليات النشر التي تتطلب مرور كل الخروج عبر وكيل التمرير الأمامي ذلك، عيّن `channels.irc.enabled=false` ما لم تتم الموافقة صراحة على الخروج المباشر عبر IRC. - وكيل التصحيح المحلي أداة تشخيص، ويكون تمريره العلوي المباشر لطلبات الوكيل وأنفاق CONNECT معطلًا افتراضيًا أثناء نشاط وضع الوكيل المُدار؛ فعّل التمرير المباشر فقط للتشخيصات المحلية المعتمدة. - يجب إدراج واجهات WebUI المحلية للمستخدم وخوادم النماذج المحلية في قائمة السماح ضمن سياسة وكيل المشغّل عند الحاجة؛ لا يوفّر OpenClaw تجاوزًا عامًا للشبكة المحلية لها. - يقتصر تجاوز وكيل مستوى تحكم Gateway عمدًا على `localhost` وعناوين URL الحرفية لعناوين IP الخاصة بحلقة الرجوع. استخدم `ws://127.0.0.1:18789` أو `ws://[::1]:18789` أو `ws://localhost:18789` لاتصالات مستوى تحكم Gateway المحلية المباشرة؛ وتُوجّه أسماء المضيفين الأخرى كحركة مرور عادية مستندة إلى اسم المضيف. - لا يفحص OpenClaw سياسة الوكيل الخاصة بك ولا يختبرها ولا يصادق عليها. - تعامل مع تغييرات سياسة الوكيل كتغييرات تشغيلية حساسة أمنيًا. | السطح | حالة الوكيل المُدار | | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | `fetch`, `node:http`, `node:https`, common WebSocket clients | تُوجَّه عبر خطافات الوكيل المُدار عند تكوينها. | | APNs direct HTTP/2 | تُوجَّه عبر مساعد CONNECT المُدار الخاص بـ APNs. | | Gateway control-plane loopback | مباشر فقط لعنوان URL الخاص بـ Gateway ذي local loopback المُكوَّن. | | Debug proxy upstream forwarding | معطّل أثناء نشاط وضع الوكيل المُدار ما لم يُفعّل صراحة للتشخيصات المحلية. | | IRC | TCP/TLS خام؛ لا يُوكَّل بواسطة وضع وكيل HTTP المُدار. عطّله ما لم تتم الموافقة على خروج IRC مباشر. | | Other raw `net`, `tls`, or `http2` client calls | يجب تصنيفها بواسطة حارس المقبس الخام قبل الدمج. |