OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

اكتشاف Bonjour

يمكن لـ OpenClaw استخدام Bonjour ‏(mDNS/DNS-SD) لاكتشاف Gateway نشط (نقطة نهاية WebSocket). يُعد تصفح البث المتعدد local. وسيلة ملائمة داخل الشبكة المحلية فقط: يتولى Plugin ‏bonjour المضمّن الإعلان داخل الشبكة المحلية، ويبدأ تلقائيًا على مضيفي macOS ويتطلب التفعيل الاختياري على Linux وWindows وعمليات نشر Gateway ضمن حاويات. ويمكن للمنارة نفسها أيضًا النشر عبر نطاق DNS-SD واسع النطاق مُهيأ للاكتشاف عبر الشبكات. يعمل الاكتشاف وفق أفضل جهد ولا يحل محل الاتصال المستند إلى SSH أو Tailnet.

Bonjour واسع النطاق (DNS-SD أحادي الإرسال) عبر Tailscale

إذا كان الـ Node والـ Gateway على شبكتين مختلفتين، فلا يمكن لبث mDNS المتعدد عبور الحد الفاصل. حافظ على تجربة مستخدم الاكتشاف نفسها بالتبديل إلى DNS-SD أحادي الإرسال ("Bonjour واسع النطاق") عبر Tailscale:

  1. شغّل خادم DNS على مضيف Gateway بحيث يمكن الوصول إليه عبر Tailnet.
  2. انشر سجلات DNS-SD لـ _openclaw-gw._tcp ضمن منطقة مخصصة (مثال: openclaw.internal.).
  3. هيّئ DNS المقسّم في Tailscale بحيث يُحل النطاق الذي اخترته عبر خادم DNS هذا للعملاء، بما في ذلك iOS.

النطاق openclaw.internal. أعلاه مجرد مثال — يدعم OpenClaw أي نطاق اكتشاف. تتصفح عُقد iOS/Android كلًا من local. ونطاقك واسع النطاق المُهيأ.

إعدادات Gateway

json5
{  gateway: { bind: "tailnet" }, // للشبكة الطرفية فقط (موصى به)  discovery: { wideArea: { enabled: true, domain: "openclaw.internal" } },}

يقبل discovery.wideArea.domain أيضًا متغير البيئة OPENCLAW_WIDE_AREA_DOMAIN كخيار احتياطي عندما لا تكون قيمته معيّنة.

إعداد خادم DNS لمرة واحدة (مضيف Gateway، على macOS فقط)

bash
openclaw dns setup --apply

هذا الأمر مخصص لـ macOS فقط ويتطلب Homebrew واتصال Tailscale قيد التشغيل. يثبّت CoreDNS ‏(brew install coredns) ويهيئه من أجل:

  • الاستماع على المنفذ 53 على واجهات Tailscale الخاصة بـ Gateway فقط
  • خدمة النطاق الذي اخترته (مثال: openclaw.internal.) من ~/.openclaw/dns/<domain>.db

شغّله أولًا من دون --apply لمعاينة الخطة (النطاق، ومسار ملف المنطقة، وعنوان IP المكتشف لـ Tailnet، والإعدادات الموصى بها) من دون تثبيت أي شيء.

تحقق من جهاز متصل بـ Tailnet:

bash
dns-sd -B _openclaw-gw._tcp openclaw.internal.dig @&lt;TAILNET_IPV4&gt; -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

إعدادات DNS في Tailscale

في وحدة تحكم إدارة Tailscale:

  • أضف خادم أسماء يشير إلى عنوان IP الخاص بـ Tailnet لـ Gateway ‏(UDP/TCP 53).
  • أضف DNS مقسّمًا بحيث يستخدم نطاق الاكتشاف خادم الأسماء هذا.

بعد قبول العملاء لـ DNS الخاص بـ Tailnet، يمكن لعُقد iOS واكتشاف CLI تصفح _openclaw-gw._tcp في نطاق الاكتشاف من دون بث متعدد.

أمان مستمع Gateway

يرتبط منفذ WS الخاص بـ Gateway (الافتراضي 18789) بالواجهة المحلية افتراضيًا. للوصول عبر الشبكة المحلية/Tailnet، اربطه صراحةً وأبقِ المصادقة مفعّلة. لعمليات الإعداد المقصورة على Tailnet، عيّن gateway.bind: "tailnet" في ~/.openclaw/openclaw.json وأعد تشغيل Gateway (أو تطبيق شريط القوائم في macOS).

ما الذي يُعلَن عنه

يعلن Gateway وحده عن _openclaw-gw._tcp. يأتي إعلان البث المتعدد داخل الشبكة المحلية من Plugin ‏bonjour المضمّن عند تفعيله؛ بينما يظل نشر DNS-SD واسع النطاق مملوكًا لـ Gateway.

أنواع الخدمات

  • _openclaw-gw._tcp - منارة نقل Gateway، تستخدمها عُقد macOS/iOS/Android.

مفاتيح TXT (تلميحات غير سرية)

المفتاح وقت وجوده
role=gateway دائمًا.
displayName=<friendly name> دائمًا.
lanHost=<hostname>.local دائمًا.
gatewayPort=<port> دائمًا (Gateway WS + HTTP).
transport=gateway دائمًا.
gatewayTls=1 فقط عند تفعيل TLS.
gatewayTlsSha256=<sha256> فقط عند تفعيل TLS وتوفر بصمة.
gatewayDirectReachable=1 فقط عندما يمكن الوصول إلى Gateway مباشرةً (وليس فقط عبر مسار ترحيل/وكيل).
canvasPort=<port> فقط عند تفعيل مضيف اللوحة؛ وهو حاليًا مماثل لـ gatewayPort.
tailnetDns=<magicdns> وضع mDNS الكامل فقط؛ تلميح اختياري عند توفر Tailnet.
sshPort=<port> الوضع الكامل فقط؛ يُحذف في الوضعين الأدنى والمتوقف.
cliPath=<path> الوضع الكامل فقط؛ يُحذف في الوضعين الأدنى والمتوقف.

ملاحظات أمنية:

  • سجلات TXT الخاصة بـ Bonjour/mDNS غير موثّقة. يجب ألا يتعامل العملاء مع TXT بوصفه مرجعًا موثوقًا للتوجيه.
  • ينبغي للعملاء إجراء التوجيه باستخدام نقطة نهاية الخدمة التي جرى حلها (SRV + A/AAAA). تعامل مع lanHost وtailnetDns وgatewayPort وgatewayTlsSha256 كتلميحات فقط.
  • ينبغي كذلك للاستهداف التلقائي عبر SSH استخدام مضيف الخدمة الذي جرى حله، وليس تلميحات TXT وحدها.
  • يجب ألا يسمح تثبيت TLS مطلقًا لقيمة gatewayTlsSha256 مُعلنة بتجاوز تثبيت محفوظ سابقًا.
  • ينبغي لعُقد iOS/Android التعامل مع الاتصالات المباشرة المستندة إلى الاكتشاف على أنها مقصورة على TLS، وطلب تأكيد صريح من المستخدم قبل الوثوق ببصمة لأول مرة.

تصحيح الأخطاء على macOS

الأدوات المضمّنة:

bash
# تصفح المثيلاتdns-sd -B _openclaw-gw._tcp local. # حل مثيل واحد (استبدل <instance>)dns-sd -L "<instance>" _openclaw-gw._tcp local.

إذا نجح التصفح وفشل الحل، فعادةً ما تكون المشكلة في سياسة الشبكة المحلية أو محلل mDNS.

تصحيح الأخطاء في سجلات Gateway

يكتب Gateway ملف سجل متجددًا (يُطبع عند بدء التشغيل باسم gateway log file: ...). ابحث عن أسطر bonjour:، وخصوصًا:

  • bonjour: advertise failed ...
  • bonjour: suppressing ciao netmask assertion ...
  • bonjour: ... name conflict resolved / hostname conflict resolved

يشغّل OpenClaw كل خدمة Bonjour مرة واحدة ويترك الاستقصاء وإعادة المحاولة وحل تعارض الأسماء وإعادة النشر عند تغيّر الواجهات لمستجيب mDNS. يمنع ذلك تداخل محاولات النشر أثناء التقلبات المعتادة في الشبكة. تُمنع رسائل الاستقصاء الذاتي الداخلية المتكررة كي لا تغمر سجل Gateway.

عندما تعلن عدة بوابات OpenClaw من المضيف نفسه، قد يضيف Bonjour لاحقات مثل (2) أو (3) للحفاظ على تفرّد أسماء مثيلات الخدمة. هذه اللاحقات إجراء طبيعي لحل التعارض ولا تشير إلى إشراف OCM مكرر.

يستخدم Bonjour اسم مضيف النظام لمضيف .local المُعلن عندما يكون تسمية DNS صالحة. إذا احتوى اسم مضيف النظام على مسافات أو شرطات سفلية أو محرف آخر غير صالح في تسمية DNS، يعود OpenClaw إلى openclaw.local. عيّن OPENCLAW_MDNS_HOSTNAME=<name> قبل بدء Gateway عندما تحتاج إلى تسمية مضيف صريحة.

تصحيح الأخطاء على Node بنظام iOS

يستخدم Node بنظام iOS ‏NWBrowser لاكتشاف _openclaw-gw._tcp.

لالتقاط السجلات: Settings -> Gateway -> Advanced -> Discovery Debug Logs، ثم Settings -> Gateway -> Advanced -> Discovery Logs -> أعد إنتاج المشكلة -> Copy. يتضمن السجل انتقالات حالة المتصفح وتغييرات مجموعة النتائج.

متى ينبغي تفعيل Bonjour

يبدأ Bonjour تلقائيًا عند تشغيل Gateway بإعدادات فارغة على مضيفي macOS، لأن التطبيق المحلي وعُقد iOS/Android القريبة تعتمد عادةً على الاكتشاف ضمن الشبكة المحلية نفسها.

فعّله صراحةً عندما يكون الاكتشاف التلقائي ضمن الشبكة المحلية نفسها مفيدًا على Linux أو Windows أو مضيف آخر غير macOS:

bash
openclaw plugins enable bonjour

عند تفعيله، يستخدم Bonjour ‏discovery.mdns.mode لتحديد مقدار بيانات TXT الوصفية التي سينشرها؛ ويتحكم الوضع نفسه في تلميحات TXT الاختيارية ضمن سجلات DNS-SD واسعة النطاق. الأوضاع:

الوضع السلوك
minimal (الافتراضي) مفاتيح TXT الأساسية فقط؛ يحذف sshPort وcliPath وtailnetDns.
full يضيف sshPort وcliPath وtailnetDns — استخدمه عندما يحتاج العملاء إلى هذه التلميحات.
off يمنع البث المتعدد داخل الشبكة المحلية من دون تغيير حالة تفعيل Plugin؛ ويظل بإمكان DNS-SD واسع النطاق نشر المنارة الدنيا عندما تكون discovery.wideArea.enabled صحيحة.

متى ينبغي تعطيل Bonjour

اترك Bonjour معطّلًا عندما يكون إعلان البث المتعدد داخل الشبكة المحلية غير ضروري أو غير متاح أو ضارًا — تشمل الحالات الشائعة خوادم غير macOS وشبكات Docker الجسرية وWSL أو سياسة شبكة تُسقط بث mDNS المتعدد. يظل Gateway قابلًا للوصول عبر عنوان URL المنشور أو SSH أو Tailnet أو DNS-SD واسع النطاق؛ ولا يصبح غير موثوق سوى الاكتشاف التلقائي داخل الشبكة المحلية.

استخدم تجاوز متغير البيئة للمشكلات الخاصة بعملية النشر (آمن لصور Docker وملفات الخدمة وبرامج نصية للتشغيل وتصحيح الأخطاء لمرة واحدة — ويختفي عند اختفاء البيئة):

bash
OPENCLAW_DISABLE_BONJOUR=1

استخدم إعدادات Plugin عندما تريد عمدًا إيقاف Plugin اكتشاف الشبكة المحلية المضمّن لإعداد OpenClaw ذاك:

bash
openclaw plugins disable bonjour

محاذير Docker

يعطّل Plugin ‏Bonjour المضمّن إعلان البث المتعدد داخل الشبكة المحلية تلقائيًا في الحاويات المكتشفة عندما لا تكون OPENCLAW_DISABLE_BONJOUR معيّنة. عادةً لا تمرّر شبكات Docker الجسرية بث mDNS المتعدد (224.0.0.251:5353) بين الحاوية والشبكة المحلية، ولذلك نادرًا ما يجعل الإعلان من الحاوية الاكتشاف يعمل.

محاذير:

  • يبدأ Bonjour تلقائيًا على مضيفي macOS ويتطلب التفعيل الاختياري في الأنظمة الأخرى. لا يؤدي تركه معطّلًا إلى إيقاف Gateway — بل يتخطى فقط إعلان البث المتعدد داخل الشبكة المحلية.
  • لا يؤدي تعطيل Bonjour إلى تغيير gateway.bind؛ إذ يظل Docker يستخدم OPENCLAW_GATEWAY_BIND=lan افتراضيًا حتى يعمل منفذ المضيف المنشور.
  • لا يؤدي تعطيل Bonjour إلى تعطيل DNS-SD واسع النطاق. استخدم الاكتشاف واسع النطاق أو Tailnet عندما لا يكون Gateway والـ Node على الشبكة المحلية نفسها.
  • لا تؤدي إعادة استخدام OPENCLAW_CONFIG_DIR نفسها خارج Docker إلى استمرار سياسة التعطيل التلقائي للحاوية.
  • عيّن OPENCLAW_DISABLE_BONJOUR=0 فقط لشبكات المضيف أو macvlan أو شبكة أخرى يُعرف أن بث mDNS المتعدد يمر عبرها؛ وعيّنها إلى 1 لفرض التعطيل.

استكشاف أخطاء Bonjour المعطّل وإصلاحها

إذا توقف Node عن الاكتشاف التلقائي لـ Gateway بعد إعداد Docker:

  1. تحقق مما إذا كان Gateway يعمل في الوضع التلقائي أو وضع التشغيل القسري أو وضع الإيقاف القسري:

    bash
    docker compose config | grep OPENCLAW_DISABLE_BONJOUR

  2. تحقق من إمكانية الوصول إلى Gateway نفسه عبر المنفذ المنشور:

    bash
    curl -fsS http://127.0.0.1:18789/healthz

  3. استخدم هدفًا مباشرًا عند تعطيل Bonjour:

    • واجهة التحكم أو الأدوات المحلية: http://127.0.0.1:18789
    • عملاء الشبكة المحلية: http://<gateway-host>:18789
    • العملاء عبر الشبكات: Tailnet MagicDNS أو عنوان IP لـ Tailnet أو نفق SSH أو DNS-SD واسع النطاق

  4. إذا فعّلت Plugin ‏Bonjour عمدًا في Docker وفرضت الإعلان باستخدام OPENCLAW_DISABLE_BONJOUR=0، فاختبر البث المتعدد من المضيف:

    bash
    dns-sd -B _openclaw-gw._tcp local.

    إذا كان التصفح فارغًا، أو أظهرت سجلات Gateway إخفاقات متكررة في استقصاء ciao، فأعد OPENCLAW_DISABLE_BONJOUR=1 واستخدم مسارًا مباشرًا أو عبر Tailnet.

أوضاع الفشل الشائعة

  • لا يتجاوز Bonjour حدود الشبكات: استخدم Tailnet أو SSH.
  • البث المتعدد محظور: تعطّل بعض شبكات Wi-Fi بروتوكول mDNS.
  • توقّف المعلِن في مرحلة الاستقصاء/الإعلان: قد تؤدي الأجهزة المضيفة التي يُحظر فيها البث المتعدد، أو جسور الحاويات، أو WSL، أو التغيّرات المتكررة في الواجهات إلى إبقاء المستجيب في حالة غير معلَنة. يظل Gateway متاحًا عبر المسارات المباشرة أو SSH أو Tailnet أو DNS-SD واسع النطاق؛ عطّل Bonjour للشبكة المحلية باستخدام discovery.mdns.mode: "off" أو OPENCLAW_DISABLE_BONJOUR=1 عندما لا يكون البث المتعدد متاحًا.
  • شبكات جسور Docker: يُعطَّل Bonjour تلقائيًا داخل الحاويات المكتشفة. اضبط OPENCLAW_DISABLE_BONJOUR=0 فقط للشبكة المضيفة أو macvlan أو شبكة أخرى تدعم mDNS.
  • السكون/التغيّرات المتكررة في الواجهات: قد يُسقط macOS نتائج mDNS مؤقتًا؛ أعد المحاولة.
  • يعمل التصفح لكن تفشل عملية الحل: أبقِ أسماء الأجهزة بسيطة (تجنّب الرموز التعبيرية أو علامات الترقيم)، ثم أعد تشغيل Gateway. يُشتق اسم مثيل الخدمة من اسم المضيف، لذا قد تربك الأسماء شديدة التعقيد بعض أدوات الحل.

أسماء المثيلات المُهَرَّبة (\032)

غالبًا ما يُهَرِّب Bonjour/DNS-SD البايتات في أسماء مثيلات الخدمة على هيئة تسلسلات عشرية \DDD (تتحول المسافات إلى \032). هذا طبيعي على مستوى البروتوكول؛ وينبغي لواجهات المستخدم فك ترميزها للعرض (يستخدم iOS ‏BonjourEscapes.decode).

التمكين / التعطيل / الإعداد

الإعداد التأثير
openclaw plugins enable bonjour يمكّن Plugin اكتشاف الشبكة المحلية المضمّن على الأجهزة المضيفة التي لا يكون مفعّلًا عليها افتراضيًا.
openclaw plugins disable bonjour يعطّل إعلانات البث المتعدد للشبكة المحلية عبر تعطيل Plugin المضمّن.
OPENCLAW_DISABLE_BONJOUR=1 (أو true/yes/on) يعطّل إعلانات البث المتعدد للشبكة المحلية دون تغيير إعداد Plugin.
OPENCLAW_DISABLE_BONJOUR=0 (أو false/no/off) يفرض تشغيل إعلانات البث المتعدد للشبكة المحلية، بما في ذلك داخل الحاويات المكتشفة.
discovery.mdns.mode off | minimal (الافتراضي) | full — راجع الأوضاع أعلاه.
gateway.bind يتحكم في وضع ربط Gateway ضمن ~/.openclaw/openclaw.json.
OPENCLAW_SSH_PORT يتجاوز منفذ SSH عندما يُعلَن sshPort (الوضع الكامل).
OPENCLAW_TAILNET_DNS ينشر تلميح MagicDNS في TXT عند تمكين الوضع الكامل لـ mDNS.
OPENCLAW_CLI_PATH يتجاوز مسار CLI المُعلَن (الوضع الكامل).

تبدأ أجهزة macOS المضيفة تشغيل Plugin اكتشاف الشبكة المحلية المضمّن تلقائيًا بشكل افتراضي. عندما يكون Plugin ‏Bonjour مفعّلًا ولا تكون OPENCLAW_DISABLE_BONJOUR مضبوطة، يعلن Bonjour على الأجهزة المضيفة العادية ويتعطّل تلقائيًا داخل الحاويات المكتشفة (Docker وأجهزة Fly.io وبيئات تشغيل الحاويات الشائعة).

مستندات ذات صلة

Was this useful?
On this page

On this page