الإعداد
proxy.enabled: true في الإعداد:
proxy.proxyUrl على OPENCLAW_PROXY_URL. إذا كانت proxy.enabled تساوي true ولكن لم يُحدَّد عنوان URL صالح، تفشل الأوامر المحمية عند بدء التشغيل بدلاً من الرجوع إلى الوصول المباشر إلى الشبكة.
بالنسبة إلى خدمات Gateway المُدارة، خزّن عنوان URL في الإعداد كي يستمر بعد إعادة التثبيت، بدلاً من الاعتماد على بيئة العملية الأمامية:
OPENCLAW_PROXY_URL أنسب للتشغيل في الواجهة الأمامية. لاستخدامه مع خدمة مثبّتة، ضعه في البيئة الدائمة للخدمة ($OPENCLAW_STATE_DIR/.env، والقيمة الافتراضية ~/.openclaw/.env)، ثم أعد التثبيت كي تلتقطه launchd أو systemd أو Scheduled Tasks.
نقطة نهاية وكيل HTTPS باستخدام CA خاصة
proxy.tls.caFile من شهادة TLS الخاصة بنقطة نهاية الوكيل نفسها. وهو ليس إعداد ثقة MITM للوجهة، ولا شهادة عميل، ولا بديلاً عن سياسة الوجهات الخاصة بالوكيل. استخدم NODE_EXTRA_CA_CERTS بدلاً منه فقط عندما يجب أن تثق عملية Node بأكملها في CA إضافية منذ بدء التشغيل (على سبيل المثال، نظام مؤسسي لفحص TLS يعيد توقيع كل شهادة لوجهة HTTPS) — فهذا المتغير عام على مستوى العملية ويجب تعيينه قبل بدء Node، لذا لا يمكن لـ OpenClaw تطبيقه أثناء التشغيل بالطريقة التي يطبّق بها proxy.tls.caFile. يُفضَّل استخدام proxy.tls.caFile للثقة في نقطة نهاية وكيل HTTPS، إذ يقتصر نطاقه على توجيه الوكيل المُدار بدلاً من العملية بأكملها.
آلية عمل التوجيه
عند استخدامproxy.enabled: true وعنوان URL صالح، توجّه عمليات وقت التشغيل المحمية (openclaw gateway run وopenclaw node run وopenclaw agent --local) حركة خروج HTTP وWebSocket العادية عبر الوكيل:
fetch، والعملاء المعتمدين على undici، وnode:http/node:https، وعملاء WebSocket الشائعين، وأنفاق CONNECT التي تنشئها الأدوات المساعدة، كما يستبدل وكلاء HTTP في Node الذين يوفّرهم المستدعي بحيث لا تتمكن الوكلاء الصريحة (بما في ذلك axios وgot وnode-fetch والعملاء المشابهون المعتمدون على وكلاء Node) من تجاوز الوكيل بصمت.
يصف مخطط عنوان URL للوكيل مرحلة الاتصال من OpenClaw إلى الوكيل، وليس إلى الوجهة النهائية:
http://proxy.example:3128— اتصال TCP عادي بالوكيل؛ يرسل OpenClaw طلبات وكيل HTTP، بما في ذلكCONNECTلوجهات HTTPS.https://proxy.example:8443— يفتح OpenClaw اتصال TLS بالوكيل نفسه (مع التحقق من شهادة الوكيل)، ثم يرسل طلبات وكيل HTTP داخل تلك الجلسة.
CONNECT من الوكيل ويبدأ TLS الخاص بالوجهة عبر ذلك النفق.
أثناء نشاط الوكيل، يمسح OpenClaw المتغيرين no_proxy/NO_PROXY. تعتمد قوائم التجاوز هذه على الوجهة؛ وسيتيح إبقاء localhost أو 127.0.0.1 فيها لأهداف SSRF تخطي الوكيل بالكامل. عند إيقاف التشغيل، يستعيد OpenClaw بيئة الوكيل السابقة ويعيد ضبط حالة التوجيه المخزّنة مؤقتًا.
تمتلك بعض Plugin وسيلة نقل مخصصة تتطلب إعداد وكيل خاصًا بها حتى عند تفعيل التوجيه على مستوى العملية. يستخدم عميل Bot API في Telegram موزّع undici خاصًا به يعمل عبر HTTP/1، ويراعي بصورة مستقلة متغيرات بيئة الوكيل الخاصة بالعملية، إضافةً إلى الرجوع إلى OPENCLAW_PROXY_URL.
وضع local loopback في Gateway
يتصل عملاء مستوى التحكم المحلي في Gateway عادةً بـ WebSocket عبر local loopback، مثلws://127.0.0.1:18789. يتحكم proxy.loopbackMode فيما إذا كانت حركة المرور هذه تتجاوز الوكيل المُدار:
يقتصر تجاوز مستوى التحكم في Gateway على
localhost وعناوين URL التي تستخدم عناوين IP حرفية لـ local loopback — استخدم ws://127.0.0.1:18789 أو ws://[::1]:18789 أو ws://localhost:18789. تُوجَّه أسماء المضيفين الأخرى مثل حركة المرور العادية.
الحاويات
بالنسبة إلى أوامرopenclaw --container ...، يمرّر OpenClaw OPENCLAW_PROXY_URL إلى CLI الفرعي المستهدف للحاوية عند تعيينه. يجب أن يكون عنوان URL قابلاً للوصول من داخل الحاوية — إذ يشير 127.0.0.1 هناك إلى الحاوية نفسها، لا إلى المضيف. يرفض OpenClaw عناوين URL للوكيل عبر local loopback في الأوامر المستهدفة للحاويات ما لم تعيّن OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1 لتجاوز هذا الفحص صراحةً.
مصطلحات الوكيل ذات الصلة
proxy.enabled/proxy.proxyUrl— توجيه وكيل إعادة التوجيه الصادر لحركة الخروج في وقت التشغيل. تتناول هذه الصفحة ذلك.gateway.auth.mode: "trusted-proxy"— مصادقة وكيل عكسي واردة ومدركة للهوية للوصول إلى Gateway. راجع مصادقة الوكيل الموثوق.openclaw proxy— وكيل تصحيح أخطاء محلي وأداة فحص لالتقاط البيانات لأغراض التطوير والدعم. راجع openclaw proxy.tools.web.fetch.useTrustedEnvProxy— اشتراك اختياري لـweb_fetchللسماح لوكيل بيئة HTTP(S) يتحكم فيه المشغّل بتحليل DNS، مع الإبقاء افتراضيًا على التثبيت الصارم لـ DNS وسياسة أسماء المضيفين. راجع جلب الويب.- إعدادات الوكيل الخاصة بالقناة أو الموفّر — تجاوزات خاصة بالمالك لوسيلة نقل واحدة. يُفضَّل وكيل الشبكة المُدار للتحكم المركزي في حركة الخروج عبر بيئة التشغيل.
التحقق من الوكيل
تمثّل سياسة وجهات الوكيل الحد الأمني الفعلي؛ ولا يستطيع OpenClaw التحقق من أن وكيلك يحظر الأهداف الصحيحة. اضبطه كي:- يرتبط فقط بـ local loopback أو واجهة خاصة موثوقة، ولا يمكن الوصول إليه إلا من خلال عملية OpenClaw أو مضيفها أو حاويتها أو حساب خدمتها.
- يحل الوجهات بنفسه ويحظرها بحسب عنوان IP بعد تحليل DNS، وقت الاتصال، لكل من HTTP العادي وأنفاق HTTPS باستخدام
CONNECT. - يرفض عمليات التجاوز المعتمدة على الوجهة لنطاقات local loopback والخاصة والمحلية للرابط وبيانات التعريف والبث المتعدد والمحجوزة ونطاقات التوثيق.
- يتجنب قوائم السماح لأسماء المضيفين ما لم تكن تثق تمامًا في مسار تحليل DNS.
- يسجّل الوجهة والقرار والحالة والسبب — ولا يسجّل أبدًا أجسام الطلبات أو ترويسات التفويض أو ملفات تعريف الارتباط أو الأسرار الأخرى.
- يبقي السياسة تحت التحكم في الإصدارات ويراجع التغييرات باعتبارها حساسة أمنيًا.
إذا لم تكن قيمة
proxy.enabled هي true ولم يُمرر --proxy-url، فسيبلغ الأمر عن مشكلة في الإعدادات بدلًا من إجراء التحقق؛ مرّر --proxy-url لإجراء فحص تمهيدي لمرة واحدة قبل تغيير الإعدادات.
عند عدم تحديد --allowed-url أو --denied-url، تكون عمليات التحقق الافتراضية كما يلي: يجب أن ينجح الوصول إلى https://example.com/، ويجب حظر خادم مؤقت لاختبار local loopback ينبغي ألا يتمكن الوكيل من الوصول إليه. ينجح فحص local loopback عند حدوث إخفاق في النقل، أو عند تلقي استجابة ليست من فئة 2xx ولا تحتوي على الرمز المميز الخاص بكل تشغيل للاختبار؛ ويفشل عند تلقي استجابة 2xx لا تحتوي على الرمز المميز (نجاح غير متوقع صادر من جهة أخرى غير خادم الاختبار)، وخصوصًا عند تلقي أي استجابة تحمل الرمز المميز المطابق، لأن ذلك يثبت أن الوكيل مرّر بالفعل وجهة local loopback كان ينبغي له رفضها. لا تتضمن أهداف --denied-url المخصصة رمز الاختبار هذا، لذلك تتبع نهج الإخفاق الآمن: تُعد أي استجابة HTTP دليلًا على إمكانية الوصول (فشل)، ويُبلغ عن خطأ النقل بوصفه نتيجة غير حاسمة بدلًا من إثبات الحظر، لأن OpenClaw لا يستطيع تأكيد ما إذا كان وكيلك قد رفض مصدرًا يمكن الوصول إليه أم أن عطلًا آخر قد حدث. يرسل --apns-reachable رمز موفر غير صالح عمدًا، لذلك تُعد استجابة 403 InvalidProviderToken دليلًا على وصول النفق إلى Apple. يخرج الأمر بالرمز 1 عند حدوث أي إخفاق في التحقق؛ وتُحجب بيانات اعتماد عنوان URL للوكيل في كل من المخرجات النصية ومخرجات JSON.
curl يدوي (ينبغي أن ينجح الطلب العام؛ وينبغي أن يحظر الوكيل نفسه طلبي local loopback والبيانات الوصفية — لا يستطيع curl وحده التمييز بين رفض الوكيل وتعذر الوصول إلى المصدر بالطريقة التي يستطيع بها اختبار openclaw proxy validate المدمج):
الوجهات الموصى بحظرها
قائمة حظر أولية لأي وكيل تمرير أو جدار حماية أو سياسة خروج. يوجد مصنف SSRF الخاص بـ OpenClaw فيsrc/infra/net/ssrf.ts وpackages/net-policy/src/ip.ts (BLOCKED_HOSTNAMES وBLOCKED_IPV4_SPECIAL_USE_RANGES وBLOCKED_IPV6_SPECIAL_USE_RANGES وبادئة الاختبار المعياري RFC 2544 ومعالجة IPv4 المضمن لأشكال NAT64/6to4/Teredo/ISATAP وIPv4 المعيّن) — وهي مراجع مفيدة، لكن OpenClaw لا يصدّر هذه القواعد ولا يفرضها في وكيلك الخارجي.
أضف أي مضيفات إضافية للبيانات الوصفية أو نطاقات محجوزة يوثقها مزود السحابة أو منصة الشبكة لديك.
القيود
- هذه تغطية على مستوى العملية لعملاء HTTP/WebSocket في JavaScript، وليست بيئة عزل شبكي على مستوى نظام التشغيل.
- قد تتجاوز مقابس
netوtlsوhttp2الخام، والإضافات الأصلية، والعمليات الفرعية غير التابعة لـ OpenClaw، التوجيه على مستوى Node ما لم ترث متغيرات بيئة الوكيل وتحترمها. ترث عمليات CLI الفرعية المتفرعة من OpenClaw عنوان URL للوكيل المُدار وحالةproxy.loopbackMode. - لا تشمل التجاوزات العامة للشبكة المحلية واجهات WebUI المحلية للمستخدم وخوادم النماذج المحلية — أضفها إلى قائمة السماح في سياسة وكيل المشغّل عند الحاجة. الاستثناء هو المسار المباشر المحمي لموفر تضمينات الذاكرة Ollama المضمّن، والمقيد بمصدر local loopback المحلي للمضيف المطابق تمامًا من
baseUrlالمُعدّ له؛ أما مضيفو Ollama على LAN أو الشبكة الطرفية أو الشبكة الخاصة أو العامة فما زالوا يستخدمون الوكيل المُدار. - تُعطّل افتراضيًا إعادة التوجيه المباشر إلى المنبع لوكيل التصحيح المحلي (لطلبات الوكيل وأنفاق
CONNECT) أثناء تفعيل وضع الوكيل المُدار؛ ولا تفعّلها إلا لأغراض التشخيص المحلي المعتمدة. - لا يفحص OpenClaw سياسة وكيلك ولا يختبرها ولا يعتمدها. تعامل مع تغييرات سياسة الوكيل بوصفها تغييرات تشغيلية حساسة أمنيًا.