لماذا تستخدم وكيلاً
يوفّر الوكيل للمشغّلين نقطة تحكم شبكية واحدة لحركة HTTP وWebSocket الصادرة. قد يكون ذلك مفيداً حتى خارج تقوية SSRF:- السياسة المركزية: حافظ على سياسة خروج واحدة بدلاً من الاعتماد على كل موضع استدعاء HTTP في التطبيق لضبط قواعد الشبكة بشكل صحيح.
- فحوصات وقت الاتصال: قيّم الوجهة بعد حل DNS ومباشرة قبل أن يفتح الوكيل الاتصال الصاعد.
- دفاع ضد إعادة ربط DNS: قلّل الفجوة بين فحص DNS على مستوى التطبيق والاتصال الصادر الفعلي.
- تغطية JavaScript أوسع: وجّه عملاء
fetchوnode:httpوnode:httpsوWebSocket وaxios وgot وnode-fetch والعملاء المشابهين عبر المسار نفسه. - قابلية التدقيق: سجّل الوجهات المسموح بها والمرفوضة عند حد الخروج.
- التحكم التشغيلي: افرض قواعد الوجهات، أو تقسيم الشبكة، أو حدود المعدل، أو قوائم السماح الصادرة من دون إعادة بناء OpenClaw.
كيف يوجّه OpenClaw حركة المرور
عندما تكونproxy.enabled=true ويكون عنوان URL للوكيل مهيّأً، توجّه عمليات وقت التشغيل المحمية مثل openclaw gateway run وopenclaw node run وopenclaw agent --local خروج HTTP وWebSocket العادي عبر الوكيل المهيّأ:
localhost أو عنوان IP حرفياً للـ loopback مثل 127.0.0.1 أو [::1]. يجب أن يكون مسار مستوى التحكم هذا قادراً على الوصول إلى Gateways عبر loopback حتى عندما يحظر وكيل المشغّل وجهات loopback. لا تزال طلبات HTTP وWebSocket العادية وقت التشغيل تستخدم الوكيل المهيّأ.
داخلياً، يثبّت OpenClaw Proxyline كبيئة توجيه على مستوى العملية لهذه الميزة. يغطي Proxyline fetch، والعملاء المدعومين بـ undici، ومستدعي Node الأساسيين node:http / node:https، وعملاء WebSocket الشائعين، وأنفاق CONNECT المنشأة عبر المساعدات. يستبدل وضع الوكيل المُدار وكلاء Node HTTP المقدّمين من المستدعي حتى لا تتجاوز الوكلاء الصريحة وكيل المشغّل عن غير قصد.
تملك بعض Plugins وسائل نقل مخصصة تحتاج إلى توصيل صريح بالوكيل حتى عند وجود توجيه على مستوى العملية. على سبيل المثال، يستخدم نقل Bot API في Telegram مرسلاً خاصاً به لـ HTTP/1 عبر undici ولذلك يحترم بيئة وكيل العملية إضافة إلى بديل OPENCLAW_PROXY_URL المُدار في مسار النقل الخاص بذلك المالك.
يمكن أن يستخدم عنوان URL الخاص بالوكيل إما http:// أو https://. تصف هذه المخططات الاتصال من OpenClaw إلى نقطة نهاية الوكيل:
http://proxy.example:3128: يفتح OpenClaw اتصال TCP عادياً إلى وكيل التمرير ويرسل طلبات وكيل HTTP، بما في ذلكCONNECTلوجهات HTTPS.https://proxy.example:8443: يفتح OpenClaw اتصال TLS إلى نقطة نهاية الوكيل، ويتحقق من شهادة الوكيل، ثم يرسل طلبات وكيل HTTP داخل جلسة TLS تلك.
CONNECT ثم يبدأ TLS الوجهة عبر ذلك النفق.
أثناء نشاط الوكيل، يمسح OpenClaw القيمتين no_proxy وNO_PROXY. تعتمد قوائم التجاوز هذه على الوجهة، لذلك فإن ترك localhost أو 127.0.0.1 فيها سيسمح لأهداف SSRF عالية المخاطر بتخطي وكيل الترشيح.
عند الإيقاف، يستعيد OpenClaw بيئة الوكيل السابقة ويعيد ضبط حالة توجيه العملية المخزنة مؤقتاً.
مصطلحات الوكيل ذات الصلة
proxy.enabled/proxy.proxyUrl: توجيه وكيل التمرير الصادر لخروج OpenClaw وقت التشغيل. توثّق هذه الصفحة تلك الميزة.gateway.auth.mode: "trusted-proxy": مصادقة وكيل عكسي وارد واعٍ بالهوية للوصول إلى Gateway. راجع مصادقة الوكيل الموثوق.openclaw proxy: وكيل تصحيح أخطاء محلي ومفتش التقاط للتطوير والدعم. راجع openclaw proxy.tools.web.fetch.useTrustedEnvProxy: اشتراك اختياري لـweb_fetchللسماح لوكيل بيئة HTTP(S) يتحكم به المشغّل بحل DNS مع إبقاء تثبيت DNS الصارم الافتراضي وسياسة اسم المضيف. راجع جلب الويب.- إعدادات الوكيل الخاصة بالقناة أو المزوّد: تجاوزات خاصة بالمالك لنقل معين. فضّل وكيل الشبكة المُدار عندما يكون الهدف هو التحكم المركزي في الخروج عبر وقت التشغيل.
التهيئة
proxy.enabled=true في التهيئة:
proxy.proxyUrl أسبقية على OPENCLAW_PROXY_URL.
وضع Gateway Loopback
عادةً ما يتصل عملاء مستوى التحكم المحليون في Gateway بـ WebSocket عبر loopback مثلws://127.0.0.1:18789. استخدم proxy.loopbackMode لاختيار كيفية تصرف استثناءات الوكيل المُدار للـ loopback أثناء نشاط الوكيل المُدار:
gateway-only(الافتراضي): يسجل OpenClaw سلطة loopback الخاصة بـ Gateway في سياسة التجاوز المُدارة لدى Proxyline حتى تتمكن حركة WebSocket المحلية الخاصة بـ Gateway من الاتصال مباشرة. تعمل منافذ Gateway المخصصة عبر loopback لأن مضيف ومنفذ عنوان URL النشط لـ Gateway مسجلان. يمكن للـ Plugin المتصفح المضمّن أيضاً تسجيل نقاط نهاية جاهزية CDP وWebSocket الخاصة بـ DevTools المحلية الدقيقة للمتصفحات المُدارة التي يشغّلها OpenClaw، ويمكن لمزوّد تضمينات الذاكرة Ollama المضمّن استخدام مساره المباشر المحروس الأضيق لأصل تضمين loopback المحلي للمضيف المهيّأ بدقة.proxy: لا يسجل OpenClaw تجاوزات loopback لـ Gateway أو Ollama، لذلك تُرسل حركة loopback تلك عبر الوكيل المُدار. إذا كان الوكيل بعيداً، فيجب أن يوفر توجيهاً خاصاً لخدمة loopback على مضيف OpenClaw، مثل ربطها باسم مضيف أو IP أو نفق يمكن للوكيل الوصول إليه. تحل الوكلاء البعيدة القياسية127.0.0.1وlocalhostمن مضيف الوكيل، لا من مضيف OpenClaw.block: يرفض OpenClaw اتصالات مستوى التحكم عبر loopback الخاصة بـ Gateway واتصالات loopback المحروسة لتضمين Ollama المحلي للمضيف قبل فتح مقبس.
enabled=true لكن لم يُهيَّأ عنوان URL صالح للوكيل، تفشل الأوامر المحمية عند بدء التشغيل بدلاً من الرجوع إلى الوصول المباشر إلى الشبكة.
بالنسبة إلى خدمات Gateway المُدارة التي تبدأ باستخدام openclaw gateway start، فضّل تخزين عنوان URL في التهيئة:
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 أو reserved أو documentation.
- يتجنب قوائم سماح أسماء المضيفين ما لم تكن تثق بالكامل بمسار حل DNS.
- يسجل الوجهة والقرار والحالة والسبب من دون تسجيل أجسام الطلبات أو ترويسات التفويض أو ملفات تعريف الارتباط أو الأسرار الأخرى.
- يبقي سياسة الوكيل تحت التحكم في الإصدارات ويراجع التغييرات مثل التهيئة الحساسة أمنياً.
الوجهات المحظورة الموصى بها
استخدم قائمة الرفض هذه كنقطة بداية لأي وكيل تمرير أو جدار حماية أو سياسة خروج. يعيش منطق المصنّف على مستوى تطبيق OpenClaw فيsrc/infra/net/ssrf.ts وpackages/net-policy/src/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.localdomain | local loopback عبر IPv4 |
::1/128 | local loopback عبر 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 وIPv6 المعيّن إلى IPv4 |
التحقق
تحقق من الوكيل من المضيف أو الحاوية أو حساب الخدمة نفسه الذي يشغّل OpenClaw:https://example.com/ ويبدأ عصفور loopback مؤقتًا يجب ألا يصل إليه الوكيل. ينجح فحص الرفض الافتراضي عندما يعيد الوكيل استجابة رفض غير 2xx أو يحظر العصفور بفشل نقل؛ ويفشل إذا وصلت استجابة ناجحة إلى العصفور. إذا لم يكن أي وكيل ممكّنًا ومكوّنًا، يبلغ التحقق عن مشكلة في الإعدادات؛ استخدم --proxy-url لإجراء فحص تمهيدي لمرة واحدة قبل تغيير الإعدادات. استخدم --allowed-url و--denied-url لاختبار التوقعات الخاصة بالنشر. أضف --apns-reachable للتحقق أيضًا من أن تسليم APNs HTTP/2 المباشر يمكنه فتح نفق CONNECT عبر الوكيل وتلقي استجابة APNs من sandbox؛ يستخدم الفحص رمز مزود غير صالح عمدًا، لذلك تكون 403 InvalidProviderToken متوقعة وتُحتسب كقابلة للوصول. الوجهات المرفوضة المخصصة مغلقة عند الفشل: أي استجابة HTTP تعني أن الوجهة كانت قابلة للوصول عبر الوكيل، وأي خطأ نقل يُبلّغ عنه كغير حاسم لأن OpenClaw لا يستطيع إثبات أن الوكيل حظر أصلًا قابلًا للوصول. عند فشل التحقق، يخرج الأمر بالرمز 1.
استخدم --json للأتمتة. يحتوي خرج JSON على النتيجة الإجمالية، ومصدر إعدادات الوكيل الفعال، وأي أخطاء إعدادات، وكل فحص وجهة. تُنقّح بيانات اعتماد URL الوكيل في خرج النص وJSON:
curl:
openclaw proxy validate، يستطيع عصفور loopback المضمّن التمييز بين رفض الوكيل وأصل قابل للوصول. لا تحتوي فحوصات --denied-url المخصصة على ذلك العصفور، لذلك تعامل مع كل من استجابات HTTP وإخفاقات النقل الغامضة كإخفاقات تحقق ما لم يكشف الوكيل لديك عن إشارة رفض خاصة بالنشر يمكنك التحقق منها بشكل منفصل.
ثقة CA للوكيل
استخدمproxy.tls.caFile المدار عندما تستخدم نقطة نهاية الوكيل نفسها شهادة موقعة من CA خاص:
NODE_EXTRA_CA_CERTS فقط عندما يجب أن تثق عملية Node كلها بـ CA إضافي منذ بدء العملية، مثلما يحدث عندما يعيد نظام فحص TLS مؤسسي توقيع شهادات الوجهات لكل عميل HTTPS في العملية. NODE_EXTRA_CA_CERTS عام على مستوى العملية ويجب أن يكون موجودًا قبل بدء Node. فضّل proxy.tls.caFile لثقة نقطة نهاية وكيل HTTPS لأنه محدود النطاق بتوجيه الوكيل المدار.
ثم فعّل توجيه وكيل OpenClaw:
الحدود
- يحسّن الوكيل التغطية لعملاء HTTP وWebSocket في JavaScript المحليين للعملية، لكنه ليس صندوق حماية شبكيًا على مستوى نظام التشغيل.
- تكون حركة مستوى تحكم local loopback الخاصة بـ Gateway مباشرة افتراضيًا عبر تجاوز محلي مباشر من خلال
proxy.loopbackMode: "gateway-only". ينفذ OpenClaw هذا التجاوز بتسجيل سلطة local loopback النشطة لـ Gateway في سياسة التجاوز المدارة في Proxyline. يمكن للمشغلين ضبطproxy.loopbackMode: "proxy"لإرسال حركة local loopback الخاصة بـ Gateway عبر الوكيل المدار، أوproxy.loopbackMode: "block"لرفض اتصالات Gateway عبر local loopback. راجع وضع Gateway Loopback لمعرفة التنبيه الخاص بالوكيل البعيد. - قد تتجاوز مقابس
netوtlsوhttp2الخام، والإضافات الأصلية، وعمليات الأبناء غير التابعة لـ OpenClaw توجيه الوكيل على مستوى Node ما لم ترث متغيرات بيئة الوكيل وتحترمها. ترث واجهات CLI الفرعية المتشعبة من OpenClaw عنوان URL للوكيل المدار وحالةproxy.loopbackMode. - IRC قناة TCP/TLS خام خارج توجيه وكيل التمرير الأمامي المدار بواسطة المشغل. في عمليات النشر التي تتطلب أن يمر كل الخروج عبر وكيل التمرير الأمامي ذلك، اضبط
channels.irc.enabled=falseما لم تتم الموافقة صراحةً على خروج IRC المباشر. - وكيل التصحيح المحلي أداة تشخيصية، ويكون تمريره المباشر إلى المنبع لطلبات الوكيل وأنفاق CONNECT معطلًا افتراضيًا أثناء نشاط وضع الوكيل المدار؛ فعّل التمرير المباشر فقط للتشخيصات المحلية المعتمدة.
- يجب إدراج واجهات WebUI المحلية للمستخدم وخوادم النماذج المحلية في قائمة السماح ضمن سياسة وكيل المشغل عند الحاجة؛ لا يعرّض OpenClaw تجاوزًا عامًا للشبكة المحلية لها. موفر تضمينات الذاكرة Ollama المضمّن أضيق نطاقًا: يمكنه استخدام مسار مباشر محروس فقط لأصل تضمين local loopback المضيفي الدقيق المشتق من
baseUrlالمكوّن حتى تظل تضمينات المضيف المحلي تعمل عندما لا يستطيع الوكيل المدار الوصول إلى loopback المضيف. ما زالت مضيفات تضمينات Ollama على LAN وtailnet والشبكات الخاصة والعامة تستخدم مسار الوكيل المدار. يرسلproxy.loopbackMode: "proxy"حركة Ollama عبر loopback هذه عبر الوكيل المدار، ويرفضهاproxy.loopbackMode: "block"قبل فتح اتصال. - يقتصر تجاوز وكيل مستوى تحكم Gateway عمدًا على
localhostوعناوين URL ذات IP loopback الحرفية. استخدمws://127.0.0.1:18789أوws://[::1]:18789أوws://localhost:18789لاتصالات مستوى تحكم Gateway المحلية المباشرة؛ تُوجّه أسماء المضيفين الأخرى مثل حركة المرور العادية القائمة على اسم المضيف. - لا يفحص OpenClaw سياسة الوكيل لديك أو يختبرها أو يصادق عليها.
- تعامل مع تغييرات سياسة الوكيل كتغييرات تشغيلية حساسة أمنيًا.
| السطح | حالة الوكيل المدار |
|---|---|
fetch, node:http, node:https, عملاء WebSocket الشائعون | تُوجّه عبر خطافات الوكيل المدار عند تكوينها. |
| APNs HTTP/2 المباشر | يُوجّه عبر مساعد CONNECT المدار لـ APNs. |
| local loopback لمستوى تحكم Gateway | مباشر فقط لعنوان URL المحلي المكوّن لـ Gateway عبر loopback. |
| تمرير المنبع لوكيل التصحيح | معطل أثناء نشاط وضع الوكيل المدار ما لم يُفعّل صراحةً للتشخيصات المحلية. |
| IRC | TCP/TLS خام؛ لا يمر عبر وضع وكيل HTTP المدار. عطّله ما لم تتم الموافقة على خروج IRC المباشر. |
نداءات العملاء الأخرى الخام عبر net أو tls أو http2 | يجب تصنيفها بواسطة حارس المقابس الخام قبل الدمج. |