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

Documentation Index

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

​
وضع حلقة رجوع Gateway

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

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

سياسة الوكيل هي حد الأمان. لا يستطيع OpenClaw التحقق من أن الوكيل يحظر الأهداف الصحيحة. هيّئ الوكيل لكي:
  • يرتبط بحلقة الرجوع فقط أو بواجهة خاصة موثوقة.
  • يقيّد الوصول بحيث لا يستطيع استخدامه إلا عملية OpenClaw أو المضيف أو الحاوية أو حساب الخدمة.
  • يحل الوجهات بنفسه ويحظر عناوين IP للوجهات بعد حل DNS.
  • يطبّق السياسة وقت الاتصال لكل من طلبات HTTP العادية وأنفاق HTTPS CONNECT.
  • يرفض التجاوزات المبنية على الوجهة لحلقة الرجوع والنطاقات الخاصة والمحلية للرابط والبيانات الوصفية والبث المتعدد والمحجوزة أو نطاقات التوثيق.
  • يتجنب قوائم السماح بأسماء المضيفين ما لم تكن تثق تمامًا بمسار حل 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
::1/128حلقة رجوع 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/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 ومعيّن إلى IPv4
إذا وثّق مزوّد السحابة أو منصة الشبكة لديك مضيفين إضافيين للبيانات الوصفية أو نطاقات محجوزة، فأضفها أيضًا.

​
التحقق

تحقق من الوكيل من المضيف أو الحاوية أو حساب الخدمة نفسه الذي يشغّل 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 من بيئة الحماية؛ يستخدم المسبار رمز موفّر غير صالح عمدًا، لذلك يكون 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

​
الحدود

  • يحسّن الوكيل التغطية لعملاء JavaScript HTTP وWebSocket المحليين ضمن العملية، لكنه ليس صندوق حماية شبكيًا على مستوى نظام التشغيل.
  • يكون مرور مستوى تحكم حلقة رجوع Gateway افتراضيًا كتجاوز محلي مباشر عبر proxy.loopbackMode: "gateway-only". ينفّذ OpenClaw هذا التجاوز عن طريق تسجيل سلطة حلقة رجوع Gateway النشطة في متحكم global-agent NO_PROXY المُدار. يمكن للمشغلين تعيين 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 سياسة الوكيل الخاصة بك ولا يختبرها ولا يصادق عليها.
  • تعامل مع تغييرات سياسة الوكيل كتغييرات تشغيلية حساسة أمنيًا.
السطححالة الوكيل المُدار
fetch, node:http, node:https, common WebSocket clientsتُوجَّه عبر خطافات الوكيل المُدار عند تكوينها.
APNs direct HTTP/2تُوجَّه عبر مساعد CONNECT المُدار الخاص بـ APNs.
Gateway control-plane loopbackمباشر فقط لعنوان URL الخاص بـ Gateway ذي local loopback المُكوَّن.
Debug proxy upstream forwardingمعطّل أثناء نشاط وضع الوكيل المُدار ما لم يُفعّل صراحة للتشخيصات المحلية.
IRCTCP/TLS خام؛ لا يُوكَّل بواسطة وضع وكيل HTTP المُدار. عطّله ما لم تتم الموافقة على خروج IRC مباشر.
Other raw net, tls, or http2 client callsيجب تصنيفها بواسطة حارس المقبس الخام قبل الدمج.