وكيل الشبكة

يمكن لـ OpenClaw توجيه حركة مرور HTTP وWebSocket في وقت التشغيل عبر وكيل إعادة توجيه يديره المشغّل. وهذا إجراء دفاعي اختياري متعدد الطبقات يوفّر تحكمًا مركزيًا في حركة الخروج، وحماية أقوى من SSRF، وإمكانية تدقيق الوجهات عند حدود الشبكة. ولأن الوكيل يقيّم الوجهة وقت الاتصال، بعد تحليل DNS ومباشرةً قبل فتح الاتصال بالجهة الصاعدة، فإنه يضيّق أيضًا الفجوة التي يعتمد عليها هجوم إعادة ربط DNS بين فحص DNS سابق على مستوى التطبيق والاتصال الصادر الفعلي. كما تمنح سياسة وكيل موحّدة المشغّلين موضعًا واحدًا لفرض قواعد الوجهات، أو تجزئة الشبكة، أو حدود المعدّل، أو قوائم السماح للاتصالات الصادرة دون إعادة بناء OpenClaw.

لا يوفّر OpenClaw وكيلاً ولا ينزّله أو يشغّله أو يهيّئه أو يعتمد صلاحيته. أنت تشغّل تقنية الوكيل الملائمة لبيئتك؛ ويوجّه OpenClaw عملاء HTTP وWebSocket الخاصين به عبرها.

الإعداد

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. إذا كانت proxy.enabled تساوي true ولكن لم يُحدَّد عنوان URL صالح، تفشل الأوامر المحمية عند بدء التشغيل بدلاً من الرجوع إلى الوصول المباشر إلى الشبكة.

بالنسبة إلى خدمات Gateway المُدارة، خزّن عنوان URL في الإعداد كي يستمر بعد إعادة التثبيت، بدلاً من الاعتماد على بيئة العملية الأمامية:

openclaw config set proxy.enabled trueopenclaw config set proxy.proxyUrl http://127.0.0.1:3128openclaw gateway install --forceopenclaw gateway start

يكون الرجوع إلى متغير البيئة OPENCLAW_PROXY_URL أنسب للتشغيل في الواجهة الأمامية. لاستخدامه مع خدمة مثبّتة، ضعه في البيئة الدائمة للخدمة ($OPENCLAW_STATE_DIR/.env، والقيمة الافتراضية ~/.openclaw/.env)، ثم أعد التثبيت كي تلتقطه launchd أو systemd أو Scheduled Tasks.

نقطة نهاية وكيل HTTPS باستخدام CA خاصة

proxy:  enabled: true  proxyUrl: https://proxy.corp.example:8443  tls:    caFile: /etc/openclaw/proxy-ca.pem

يتحقق proxy.tls.caFile من شهادة TLS الخاصة بنقطة نهاية الوكيل نفسها. وهو ليس إعداد ثقة MITM للوجهة، ولا شهادة عميل، ولا بديلاً عن سياسة الوجهات الخاصة بالوكيل. استخدم NODE_EXTRA_CA_CERTS بدلاً منه فقط عندما يجب أن تثق عملية Node بأكملها في CA إضافية منذ بدء التشغيل (على سبيل المثال، نظام مؤسسي لفحص TLS يعيد توقيع كل شهادة لوجهة HTTPS) — فهذا المتغير عام على مستوى العملية ويجب تعيينه قبل بدء Node، لذا لا يمكن لـ OpenClaw تطبيقه أثناء التشغيل بالطريقة التي يطبّق بها proxy.tls.caFile. يُفضَّل استخدام proxy.tls.caFile للثقة في نقطة نهاية وكيل HTTPS، إذ يقتصر نطاقه على توجيه الوكيل المُدار بدلاً من العملية بأكملها.

openclaw config set proxy.enabled trueopenclaw config set proxy.proxyUrl https://proxy.corp.example:8443openclaw config set proxy.tls.caFile /etc/openclaw/proxy-ca.pemopenclaw gateway run

آلية عمل التوجيه

عند استخدام proxy.enabled: true وعنوان URL صالح، توجّه عمليات وقت التشغيل المحمية (openclaw gateway run وopenclaw node run وopenclaw agent --local) حركة خروج HTTP وWebSocket العادية عبر الوكيل:

عملية OpenClaw  عملاء fetch وnode:http وnode:https وWebSocket  -> وكيل المشغّل -> الوجهة

داخليًا، يثبّت OpenClaw ‏Proxyline باعتباره بيئة التوجيه على مستوى العملية. وهو يغطي 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 داخل تلك الجلسة.

يكون TLS الخاص بالوجهة مستقلاً عن TLS الخاص بنقطة نهاية الوكيل: بالنسبة إلى وجهة HTTPS، يطلب OpenClaw دائمًا نفق 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 فيما إذا كانت حركة المرور هذه تتجاوز الوكيل المُدار:

proxy:  enabled: true  proxyUrl: http://127.0.0.1:3128  loopbackMode: gateway-only # gateway-only, proxy, or block

يقتصر تجاوز مستوى التحكم في 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.
• يسجّل الوجهة والقرار والحالة والسبب — ولا يسجّل أبدًا أجسام الطلبات أو ترويسات التفويض أو ملفات تعريف الارتباط أو الأسرار الأخرى.
• يبقي السياسة تحت التحكم في الإصدارات ويراجع التغييرات باعتبارها حساسة أمنيًا.

تحقّق من المضيف أو الحاوية أو حساب الخدمة نفسه الذي يشغّل OpenClaw:

openclaw proxy validate --proxy-url http://127.0.0.1:3128

مع نقطة نهاية وكيل HTTPS تستخدم CA خاصة:

openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem

إذا لم تكن قيمة 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.

{  "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 يدوي (ينبغي أن ينجح الطلب العام؛ وينبغي أن يحظر الوكيل نفسه طلبي local loopback والبيانات الوصفية — لا يستطيع curl وحده التمييز بين رفض الوكيل وتعذر الوصول إلى المصدر بالطريقة التي يستطيع بها اختبار openclaw proxy validate المدمج):

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/

الوجهات الموصى بحظرها

قائمة حظر أولية لأي وكيل تمرير أو جدار حماية أو سياسة خروج. يوجد مصنف 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 سياسة وكيلك ولا يختبرها ولا يعتمدها. تعامل مع تغييرات سياسة الوكيل بوصفها تغييرات تشغيلية حساسة أمنيًا.