اكتشاف Bonjour

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Bonjour واسع النطاق (Unicast DNS-SD) عبر Tailscale

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

​

إعداد Gateway (موصى به)

{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
}

​

إعداد خادم DNS لمرة واحدة (مضيف Gateway)

openclaw dns setup --apply

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

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

​

إعدادات DNS في Tailscale

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

​

أمان مستمع Gateway (موصى به)

• عيّن gateway.bind: "tailnet" في ~/.openclaw/openclaw.json.
• أعد تشغيل Gateway (أو أعد تشغيل تطبيق شريط القوائم في macOS).

​

ما الذي يعلن

​

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

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

​

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

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

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

​

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

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

​

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

• 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 ...

​

تصحيح الأخطاء على عقدة iOS

• Settings → Gateway → Advanced → Discovery Debug Logs
• Settings → Gateway → Advanced → Discovery Logs → أعد الإنتاج → Copy

​

متى تُفعّل Bonjour

openclaw plugins enable bonjour

​

متى تُعطّل Bonjour

OPENCLAW_DISABLE_BONJOUR=1

openclaw plugins disable bonjour

​

تنبيهات Docker

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

​

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

1. تأكد مما إذا كان Gateway يعمل في وضع auto أو forced-on أو forced-off:
   docker compose config | grep OPENCLAW_DISABLE_BONJOUR
   
2. تأكد من أن Gateway نفسه قابل للوصول عبر المنفذ المنشور:
   curl -fsS http://127.0.0.1:18789/healthz
   
3. استخدم هدفًا مباشرًا عندما يكون Bonjour معطّلًا:
   • واجهة التحكم أو الأدوات المحلية: http://127.0.0.1:18789
   • عملاء LAN: http://<gateway-host>:18789
   • العملاء عبر الشبكات: Tailnet MagicDNS أو Tailnet IP أو نفق SSH أو DNS-SD واسع النطاق
4. إذا فعّلت Plugin Bonjour عمدًا في Docker وفرضت الإعلان باستخدام OPENCLAW_DISABLE_BONJOUR=0، فاختبر Multicast من المضيف:
   dns-sd -B _openclaw-gw._tcp local.
   
   إذا كان التصفح فارغًا أو أظهرت سجلات Gateway إلغاءات متكررة من مراقب ciao، فاستعد OPENCLAW_DISABLE_BONJOUR=1 واستخدم مسارًا مباشرًا أو عبر Tailnet.

​

أنماط الفشل الشائعة

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

​

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

• هذا طبيعي على مستوى البروتوكول.
• ينبغي لواجهات المستخدم فك الترميز للعرض (يستخدم iOS BonjourEscapes.decode).

​

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

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

​

الوثائق ذات الصلة

• سياسة الاكتشاف واختيار النقل: الاكتشاف
• إقران Node + الموافقات: إقران Gateway