Security

وكيل الشبكة

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 المحلية عبر local loopback الخاصة بـ Gateway عندما يستخدم عنوان 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.
tools.web.fetch.useTrustedEnvProxy: تفعيل اختياري لـ web_fetch للسماح لوكيل بيئة HTTP(S) يتحكم به المشغّل بحل DNS مع إبقاء التثبيت الصارم الافتراضي لـ DNS وسياسة اسم المضيف. راجع جلب الويب.
إعدادات الوكيل الخاصة بالقناة أو المزوّد: تجاوزات محددة للمالك لوسيط نقل معيّن. فضّل وكيل الشبكة المُدار عندما يكون الهدف هو التحكم المركزي في الخروج عبر وقت التشغيل.

التكوين

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.

وضع Loopback في Gateway

عادةً ما يتصل عملاء مستوى التحكم المحليون لـ Gateway بـ WebSocket عبر 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-only (افتراضي): يسجّل OpenClaw سلطة loopback الخاصة بـ Gateway في متحكم NO_PROXY النشط في global-agent حتى تتمكن حركة WebSocket المحلية الخاصة بـ Gateway من الاتصال مباشرة. تعمل منافذ Gateway المخصصة عبر loopback لأن مضيف ومنفذ عنوان URL النشط الخاص بـ Gateway مسجلان.
proxy: لا يسجّل OpenClaw سلطة NO_PROXY خاصة بـ loopback في Gateway، لذلك تُرسل حركة Gateway المحلية عبر الوكيل المُدار. إذا كان الوكيل بعيدًا، فيجب أن يوفر توجيهًا خاصًا لخدمة loopback على مضيف OpenClaw، مثل ربطها باسم مضيف أو IP أو نفق يمكن للوكيل الوصول إليه. تحل الوكلاء البعيدون القياسيون 127.0.0.1 وlocalhost من مضيف الوكيل، لا من مضيف OpenClaw.
block: يرفض OpenClaw اتصالات مستوى التحكم بـ Gateway عبر loopback قبل فتح مقبس.

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

النطاق أو المضيف	سبب الحظر
`127.0.0.0/8`, `localhost`, `localhost.localdomain`	IPv4 loopback
`::1/128`	IPv6 loopback
`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::/8`	Multicast
`240.0.0.0/4`	IPv4 محجوز
`fc00::/7`, `fec0::/10`	نطاقات IPv6 المحلية/الخاصة
`100::/64`, `2001:20::/28`	نطاقات IPv6 discard و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

إذا وثّق مزوّد السحابة أو منصة الشبكة لديك مضيفي metadata إضافيين أو نطاقات محجوزة إضافية، فأضفها أيضًا.

التحقق

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

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 من بيئة sandbox؛ يستخدم المسبار رمز موفر غير صالح عمدًا، لذا فإن 403 InvalidProviderToken متوقعة وتُحتسب كقابلية وصول. الوجهات المرفوضة المخصصة مغلقة عند الفشل: أي استجابة HTTP تعني أن الوجهة كانت قابلة للوصول عبر الوكيل، وأي خطأ في طبقة النقل يُبلّغ عنه كغير حاسم لأن OpenClaw لا يستطيع إثبات أن الوكيل حظر أصلًا قابلًا للوصول. عند فشل التحقق، يخرج الأمر بالرمز 1.

استخدم --json للأتمتة. يحتوي خرج JSON على النتيجة الإجمالية، ومصدر إعدادات الوكيل الفعلي، وأي أخطاء إعدادات، وكل فحص وجهة. تُحجب بيانات اعتماد عنوان 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:

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:

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 المحليين للعملية، لكنه ليس sandbox شبكة على مستوى نظام التشغيل.
يتم تمرير حركة مرور مستوى التحكم الخاصة بالاسترجاع الحلقي لـ Gateway افتراضيًا مباشرة عبر تجاوز محلي من خلال proxy.loopbackMode: "gateway-only". ينفذ OpenClaw ذلك التجاوز عن طريق تسجيل سلطة الاسترجاع الحلقي النشطة لـ Gateway في متحكم NO_PROXY المُدار الخاص بـ global-agent. يمكن للمشغلين تعيين proxy.loopbackMode: "proxy" لإرسال حركة مرور الاسترجاع الحلقي لـ Gateway عبر الوكيل المُدار، أو proxy.loopbackMode: "block" لرفض اتصالات Gateway عبر الاسترجاع الحلقي. راجع وضع الاسترجاع الحلقي لـ Gateway لمعرفة التحذير الخاص بالوكيل البعيد.
قد تتجاوز مقابس 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 سياسة الوكيل الخاصة بك ولا يختبرها ولا يصادق عليها.
تعامل مع تغييرات سياسة الوكيل كتغييرات تشغيلية حساسة أمنيًا.

# لماذا تستخدم وكيلاً

# كيف يوجّه OpenClaw حركة المرور

# مصطلحات الوكيل ذات الصلة

# التكوين

# وضع Loopback في Gateway

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

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

# التحقق

# الحدود