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. متعدد البث ميزة ملائمة مقتصرة على الشبكة المحلية (LAN): يتولى 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" }, // مقتصر على 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 الخاص بـ Gateway في Tailnet ‏(UDP/TCP 53).
  • أضف DNS منقسمًا بحيث يستخدم نطاق الاكتشاف خادم الأسماء ذاك.

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

أمان مستمع Gateway

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

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

لا يعلن عن _openclaw-gw._tcp سوى Gateway. يأتي الإعلان متعدد البث عبر الشبكة المحلية من Plugin المضمّن bonjour عند تمكينه، بينما يظل نشر DNS-SD واسع النطاق ضمن مسؤولية Gateway.

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

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

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

المفتاح وقت وجوده
role=gateway دائمًا.
displayName=<friendly name> دائمًا.
lanHost=<hostname>.local دائمًا.
gatewayPort=<port> دائمًا (WS وHTTP الخاصان بـ Gateway).
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 cancellation ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...
  • bonjour: disabling advertiser after ... failed restarts ...

يتعامل مراقب السلامة مع حالات probing وannouncing وعمليات إعادة التسمية الحديثة الناتجة عن التعارض على أنها حالات قيد التنفيذ. إذا لم تصل الخدمة مطلقًا إلى announced، يعيد OpenClaw إنشاء المُعلِن، وبعد حالات فشل متكررة، يعطّل Bonjour لعملية Gateway تلك بدلًا من إعادة الإعلان إلى ما لا نهاية.

يستخدم 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 بقيمة true.

متى ينبغي تعطيل 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، أو التغييرات المتكررة في الواجهات إلى بقاء مُعلِن ciao في حالة غير مُعلنة. يعيد OpenClaw المحاولة بضع مرات، ثم يعطّل Bonjour لعملية Gateway الحالية بدلًا من إعادة تشغيل المُعلِن إلى أجل غير مسمى.
  • شبكة جسر 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 اكتشاف LAN المضمّن على الأجهزة المضيفة التي لا يكون مفعّلًا عليها افتراضيًا.
openclaw plugins disable bonjour يعطّل إعلانات البث المتعدد عبر LAN عن طريق تعطيل Plugin المضمّن.
OPENCLAW_DISABLE_BONJOUR=1 (أو true/yes/on) يعطّل إعلانات البث المتعدد عبر LAN دون تغيير إعداد Plugin.
OPENCLAW_DISABLE_BONJOUR=0 (أو false/no/off) يفرض تشغيل إعلانات البث المتعدد عبر LAN، بما في ذلك داخل الحاويات المكتشفة.
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 اكتشاف LAN المضمّن تلقائيًا بشكل افتراضي. عندما يكون Plugin Bonjour مفعّلًا ولا تكون قيمة OPENCLAW_DISABLE_BONJOUR مضبوطة، يعلن Bonjour على الأجهزة المضيفة العادية ويُعطَّل تلقائيًا داخل الحاويات المكتشفة (Docker وأجهزة Fly.io وبيئات تشغيل الحاويات الشائعة).

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

Was this useful?
On this page

On this page