الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
وكيل الشبكة

يمكن لـ 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 العادي عبر الوكيل المُهيّأ: 
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 loopback حرفياً مثل 127.0.0.1 أو [::1]. يجب أن يتمكن مسار مستوى التحكم هذا من الوصول إلى Gateways عبر loopback حتى عندما يحظر وكيل المشغّل وجهات loopback. تظل طلبات 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 مرسِل HTTP/1 undici خاصاً بها، ولذلك تحترم بيئة وكيل العملية بالإضافة إلى بديل 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. راجع مصادقة الوكيل الموثوق.
  • openclaw proxy: وكيل تصحيح محلي ومفتش التقاط للتطوير والدعم. راجع openclaw proxy.
  • إعدادات الوكيل الخاصة بقناة أو مزود: تجاوزات خاصة بالمالك لوسيلة نقل معينة. فضّل وكيل الشبكة المُدار عندما يكون الهدف هو التحكم المركزي في الخروج عبر وقت التشغيل.

​
الإعداد

proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128
يمكنك أيضاً توفير عنوان URL عبر البيئة، مع إبقاء proxy.enabled=true في الإعداد: 
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
تكون لـ proxy.proxyUrl أولوية على OPENCLAW_PROXY_URL. إذا كان enabled=true لكن لم تتم تهيئة عنوان URL صالح للوكيل، تفشل الأوامر المحمية عند بدء التشغيل بدلاً من الرجوع إلى الوصول المباشر إلى الشبكة. بالنسبة إلى خدمات Gateway المُدارة التي تبدأ باستخدام openclaw gateway start، فضّل تخزين عنوان URL في الإعداد: 
openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway install --force
openclaw gateway start
بديل البيئة هو الأفضل للتشغيل في الواجهة. إذا استخدمته مع خدمة مثبتة، فضع 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 لوكيل loopback للأوامر المستهدفة للحاوية ما لم تتجاوز فحص السلامة هذا صراحةً.

​
متطلبات الوكيل

سياسة الوكيل هي حد الأمان. لا يستطيع OpenClaw التحقق من أن الوكيل يحظر الأهداف الصحيحة. هيّئ الوكيل من أجل:
  • الربط فقط بـ loopback أو واجهة خاصة موثوقة.
  • تقييد الوصول بحيث لا يمكن استخدامه إلا من عملية OpenClaw أو المضيف أو الحاوية أو حساب الخدمة.
  • حل الوجهات بنفسه وحظر عناوين IP الوجهة بعد حل DNS.
  • تطبيق السياسة وقت الاتصال لكل من طلبات HTTP العادية وأنفاق HTTPS CONNECT.
  • رفض التجاوزات المعتمدة على الوجهة لنطاقات loopback أو الخاصة أو link-local أو metadata أو multicast أو المحجوزة أو نطاقات التوثيق.
  • تجنّب قوائم السماح بأسماء المضيفين إلا إذا كنت تثق تماماً في مسار حل 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-mapped. هذه الملفات مراجع مفيدة عند صيانة سياسة وكيل خارجية، لكن OpenClaw لا يصدّر هذه القواعد أو يفرضها تلقائياً في وكيلك.
النطاق أو المضيفسبب الحظر
127.0.0.0/8, localhost, localhost.localdomainloopback لـ IPv4
::1/128loopback لـ 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عناوين link-local ومسارات metadata السحابية الشائعة
169.254.169.254, metadata.google.internalخدمات metadata السحابية
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::/8multicast
240.0.0.0/4IPv4 محجوز
fc00::/7, fec0::/10نطاقات IPv6 المحلية/الخاصة
100::/64, 2001:20::/28نطاقات تجاهل IPv6 وORCHIDv2
64:ff9b::/96, 64:ff9b:1::/48بادئات NAT64 مع IPv4 مضمّن
2002::/16, 2001::/326to4 وTeredo مع IPv4 مضمّن
::/96, ::ffff:0:0/96IPv6 متوافق مع IPv4 وIPv6 معيّن إلى IPv4
إذا كان مزود السحابة أو منصة الشبكة لديك يوثّق مضيفي metadata إضافيين أو نطاقات محجوزة إضافية، فأضفها أيضاً.

​
التحقق

تحقق من الوكيل من المضيف أو الحاوية أو حساب الخدمة نفسه الذي يشغّل OpenClaw: 
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/
يجب أن ينجح الطلب العام. يجب أن تفشل طلبات loopback وmetadata عند الوكيل. بعد ذلك فعّل توجيه وكيل OpenClaw: 
openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway run
أو اضبط: 
proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128

​
الحدود

  • يحسّن الوكيل التغطية لعملاء HTTP وWebSocket في JavaScript المحليين للعملية، لكنه ليس صندوق حماية شبكي على مستوى نظام التشغيل.
  • قد تتجاوز مآخذ net وtls وhttp2 الخام، والإضافات الأصلية، والعمليات الابنة توجيه الوكيل على مستوى Node ما لم ترث متغيرات بيئة الوكيل وتحترمها.
  • يجب إضافة واجهات WebUI المحلية الخاصة بالمستخدم وخوادم النماذج المحلية إلى قائمة السماح في سياسة وكيل المشغّل عند الحاجة؛ لا يعرّض OpenClaw تجاوزاً عاماً للشبكة المحلية لها.
  • يقتصر تجاوز وكيل مستوى التحكم الخاص بـ Gateway عمداً على localhost وعناوين URL التي تحتوي على عناوين IP loopback حرفية. استخدم ws://127.0.0.1:18789 أو ws://[::1]:18789 أو ws://localhost:18789 لاتصالات مستوى التحكم المحلية المباشرة بـ Gateway؛ أما أسماء المضيفين الأخرى فتُوجّه مثل حركة المرور العادية المعتمدة على اسم المضيف.
  • لا يفحص OpenClaw سياسة الوكيل لديك، ولا يختبرها، ولا يصادق عليها.
  • تعامل مع تغييرات سياسة الوكيل كتغييرات تشغيلية حساسة أمنياً.