Skip to main content
Gateway هو خادم WebSocket الخاص بـ OpenClaw (القنوات، والعُقد، والجلسات، والخطافات). تندرج جميع الأوامر الفرعية أدناه ضمن openclaw gateway ....

اكتشاف Bonjour

إعداد mDNS المحلي وDNS-SD واسع النطاق.

نظرة عامة على الاكتشاف

كيفية إعلان OpenClaw عن بوابات Gateway والعثور عليها.

الإعداد

مفاتيح إعداد Gateway ذات المستوى الأعلى.

​
تشغيل Gateway

  • يرفض البدء ما لم يُضبط gateway.mode=local في ~/.openclaw/openclaw.json. استخدم --allow-unconfigured للتشغيلات المخصصة/التطويرية؛ إذ يتجاوز آلية الحماية دون كتابة الإعداد أو إصلاحه.
  • يكتب openclaw onboard --mode local وopenclaw setup القيمة gateway.mode=local. إذا كان ملف الإعداد موجودًا لكن gateway.mode مفقود، فيُعامل ذلك على أنه إعداد تالف/مستبدل، ويرفض Gateway افتراض local نيابةً عنك — أعد تنفيذ الإعداد الأولي، أو اضبط المفتاح يدويًا، أو مرّر --allow-unconfigured.
  • يُحظر الربط خارج local loopback دون مصادقة.
  • تُحل قيم --bind‏ lan وtailnet وcustom حاليًا عبر مسارات IPv4 فقط؛ تحتاج إعدادات المضيف المخصص التي تعمل عبر IPv6 فقط إلى حاوية جانبية أو وكيل IPv4 أمام Gateway.
  • تؤدي SIGUSR1 إلى إعادة تشغيل داخل العملية عندما تكون مخوّلة. يتحكم commands.restart (الافتراضي: مفعّل) في إشارات SIGUSR1 المرسلة خارجيًا؛ اضبطه على false لمنع إعادة التشغيل اليدوية عبر إشارات نظام التشغيل، مع استمرار السماح بإعادة التشغيل عبر الأمر gateway restart وأداة Gateway وتطبيق/تحديث الإعداد.
  • توقف SIGINT/SIGTERM العملية، لكنها لا تستعيد حالة الطرفية المخصصة — إذا غلّفت CLI داخل TUI أو إدخال في الوضع الخام، فاستعد الطرفية بنفسك قبل الخروج.

​
الخيارات

​
number
منفذ WebSocket (الافتراضي من الإعداد/متغيرات البيئة؛ عادةً 18789).
​
string
وضع الربط: loopback (الافتراضي)، وlan، وtailnet، وauto، وcustom.
​
string
الرمز المميز المشترك لـ connect.params.auth.token. تكون القيمة الافتراضية OPENCLAW_GATEWAY_TOKEN عند ضبطه.
​
string
وضع المصادقة: none، وtoken، وpassword، وtrusted-proxy.
​
string
كلمة المرور لـ --auth password.
​
string
قراءة كلمة مرور Gateway من ملف.
​
string
إتاحة Tailscale:‏ off، وserve، وfunnel.
​
boolean
إعادة ضبط إعداد serve/funnel الخاص بـ Tailscale عند الإيقاف.
​
boolean
البدء دون فرض gateway.mode=local. للتمهيد المخصص/التطويري فقط؛ ولا يحفظ الإعداد أو يصلحه.
​
boolean
إنشاء إعداد تطويري + مساحة عمل إذا كانا مفقودين (يتخطى BOOTSTRAP.md).
​
boolean
إعادة ضبط إعداد التطوير وبيانات الاعتماد والجلسات ومساحة العمل. يتطلب --dev.
​
boolean
إنهاء أي مستمع موجود على المنفذ المستهدف قبل البدء.
​
boolean
تسجيل مفصّل إلى stdout/stderr.
​
boolean
عرض سجلات الواجهة الخلفية لـ CLI فقط في وحدة التحكم (ويفعّل أيضًا stdout/stderr).
​
string
افتراضي:"auto"
نمط سجل WebSocket:‏ auto، وfull، وcompact.
​
boolean
اسم مستعار لـ --ws-log compact.
​
boolean
تسجيل أحداث تدفق النموذج الخام في JSONL.
​
string
مسار JSONL للتدفق الخام.
--claude-cli-logs اسم مستعار مهمل لـ --cli-backend-logs. بالنسبة إلى --bind custom، اضبط gateway.customBindHost على عنوان IPv4. يتطلب أي عنوان غير 127.0.0.1 أو 0.0.0.0 أيضًا وجود 127.0.0.1 على المنفذ نفسه للعملاء على المضيف ذاته؛ يفشل بدء التشغيل إذا تعذر الربط لأي من المستمعين. لا يضيف حرف البدل 0.0.0.0 اسمًا مستعارًا مطلوبًا منفصلًا. تحتاج إعدادات المضيف المخصص التي تعمل عبر IPv6 فقط إلى حاوية جانبية أو وكيل IPv4 أمام Gateway.

​
إعادة تشغيل Gateway

يطلب --safe من Gateway العامل إجراء فحص مسبق للعمل النشط وجدولة إعادة تشغيل واحدة مدمجة بعد تصريف ذلك العمل. مدة الانتظار محدودة بواسطة gateway.reload.deferralTimeoutMs (الافتراضي: 5 دقائق / 300000)؛ وعند انتهاء المهلة تُفرض إعادة التشغيل. اضبط deferralTimeoutMs: 0 للانتظار إلى أجل غير مسمى (مع تحذيرات دورية بأن العمل لا يزال معلقًا) بدلًا من الفرض. لا يمكن الجمع بين --safe و--force أو --wait. يتجاوز --skip-deferral بوابة تأجيل العمل النشط في إعادة التشغيل الآمنة، ولذلك يُعاد تشغيل Gateway فورًا حتى مع وجود عوائق مُبلّغ عنها. يتطلب --safe — استخدمه عندما يعلق التأجيل بسبب مهمة منفلتة. يتجاوز --wait <duration> ميزانية التصريف لإعادة تشغيل عادية (غير آمنة). يقبل ميلي ثانية مجردة أو لواحق الوحدات ms وs وm وh وd (مثل 30s و5m و1h30m)؛ وينتظر --wait 0 إلى أجل غير مسمى. لا يتوافق مع --force أو --safe. يتخطى --force تصريف العمل النشط ويعيد التشغيل فورًا. يحافظ restart العادي (دون خيارات) على سلوك إعادة التشغيل الحالي لمدير الخدمة.
قد تظهر قيمة --password المضمّنة في قوائم العمليات المحلية. يُفضّل استخدام --password-file أو متغيرات البيئة أو gateway.auth.password المدعوم بـ SecretRef.

​
تحليل أداء Gateway

  • يسجل OPENCLAW_GATEWAY_STARTUP_TRACE=1 توقيتات المراحل أثناء بدء التشغيل، بما فيها تأخر eventLoopMax لكل مرحلة وتوقيتات جداول بحث Plugin (فهرس العناصر المثبتة، وسجل البيانات التعريفية، وتخطيط بدء التشغيل، وعمل خريطة المالكين).
  • يسجل OPENCLAW_GATEWAY_RESTART_TRACE=1 أسطر restart trace: الخاصة بإعادة التشغيل: معالجة الإشارة، وتصريف العمل النشط، ومراحل الإيقاف، وبدء التشغيل التالي، وتوقيت الجاهزية، ومقاييس الذاكرة.
  • يكتب OPENCLAW_DIAGNOSTICS=timeline مع OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path> مخططًا زمنيًا لتشخيصات بدء التشغيل بتنسيق JSONL وبأفضل جهد ممكن لاستخدامه في أُطر QA الخارجية (وهو مكافئ للإعداد diagnostics.flags: ["timeline"]؛ ويظل المسار متاحًا عبر متغيرات البيئة فقط). أضف OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 لتضمين عينات حلقة الأحداث.
  • ينفذ pnpm build ثم pnpm test:startup:gateway -- --runs 5 --warmup 1 قياسًا مرجعيًا لبدء تشغيل Gateway مقابل نقطة دخول CLI المبنية: أول مخرجات العملية، و/healthz، و/readyz، وتوقيتات تتبع بدء التشغيل، وتأخر حلقة الأحداث، وتوقيت جدول بحث Plugin.
  • ينفذ pnpm build ثم pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5 قياسًا مرجعيًا لإعادة التشغيل داخل العملية على macOS أو Linux (غير مدعوم على Windows؛ إذ تتطلب إعادة التشغيل SIGUSR1). يستخدم SIGUSR1، ويفعّل كلا التتبعين في العملية الفرعية، ويسجل /healthz التالي، و/readyz التالي، ومدة التوقف، وتوقيت الجاهزية، ووحدة المعالجة المركزية، وRSS، ومقاييس تتبع إعادة التشغيل.
  • يمثل /healthz حيوية الخدمة؛ ويمثل /readyz جاهزية الاستخدام. تعامل مع أسطر التتبع ومخرجات القياس المرجعي بوصفها إشارات لإسناد المسؤولية إلى المالك، لا استنتاجًا كاملًا للأداء من مدة أو عينة واحدة.

​
الاستعلام من Gateway عامل

تستخدم جميع أوامر الاستعلام WebSocket RPC.
  • الافتراضي: قابل للقراءة البشرية (ملوّن في TTY).
  • --json:‏ JSON قابل للقراءة آليًا (دون تنسيق/مؤشر تحميل).
  • --no-color (أو NO_COLOR=1): تعطيل ANSI مع الحفاظ على التخطيط البشري.
عند ضبط --url، لا يرجع CLI إلى بيانات الاعتماد الموجودة في الإعداد أو متغيرات البيئة. مرّر --token أو --password صراحةً. يُعد غياب بيانات الاعتماد الصريحة خطأً.

​
gateway health

يمثل /healthz مسبارًا لحيوية الخدمة: ويعيد الاستجابة بمجرد أن يتمكن الخادم من الرد عبر HTTP. أما /readyz فأكثر صرامةً ويظل باللون الأحمر أثناء استمرار استقرار الحاويات الجانبية لـ Plugin عند بدء التشغيل، أو القنوات، أو الخطافات المُعدّة. تتضمن استجابات /readyz المحلية أو المفصّلة والمصادق عليها كتلة تشخيص eventLoop (التأخر، والاستخدام، ونسبة أنوية وحدة المعالجة المركزية، وعلامة degraded).
​
number
استهداف Gateway محلي عبر local loopback على هذا المنفذ. يتجاوز OPENCLAW_GATEWAY_URL وOPENCLAW_GATEWAY_PORT لهذا الاستدعاء.

​
gateway usage-cost

جلب ملخصات تكلفة الاستخدام من سجلات الجلسات.
​
number
افتراضي:"30"
عدد الأيام المراد تضمينها.
​
string
حصر الملخص في معرّف وكيل واحد مُعدّ.
​
boolean
التجميع عبر جميع الوكلاء المُعدّين. لا يمكن الجمع بينه وبين --agent.

​
gateway stability

جلب مسجل الاستقرار التشخيصي الحديث من Gateway عامل.
​
number
افتراضي:"25"
الحد الأقصى للأحداث الحديثة المراد تضمينها (الحد الأعلى 1000).
​
string
التصفية حسب نوع الحدث التشخيصي، مثل payload.large أو diagnostic.memory.pressure.
​
number
تضمين الأحداث التي تلي رقم تسلسل تشخيصي فقط.
​
string
قراءة حزمة استقرار محفوظة بدلًا من استدعاء Gateway العامل. يختار --bundle latest (أو --bundle وحده) أحدث حزمة ضمن دليل الحالة؛ ويمكنك أيضًا تمرير مسار JSON للحزمة مباشرةً.
​
boolean
كتابة ملف zip لتشخيصات الدعم قابل للمشاركة بدلًا من طباعة تفاصيل الاستقرار.
​
string
مسار الإخراج لـ --export.
  • تحتفظ السجلات بالبيانات التعريفية التشغيلية: أسماء الأحداث، والأعداد، وأحجام البايتات، وقراءات الذاكرة، وحالة قائمة الانتظار/الجلسة، ومعرّفات الموافقة، وأسماء القنوات/Plugin، وملخصات الجلسات المنقحة. وتستبعد نص المحادثة، ومحتويات Webhook، ومخرجات الأدوات، ومحتويات الطلبات/الاستجابات الخام، والرموز المميزة، وملفات تعريف الارتباط، والقيم السرية، وأسماء المضيفين، ومعرّفات الجلسات الخام. اضبط diagnostics.enabled: false لتعطيل المسجل بالكامل.
  • تكتب حالات الخروج القاتلة لـ Gateway، وانتهاء مهل الإيقاف، وفشل بدء التشغيل بعد إعادة التشغيل اللقطة التشخيصية نفسها إلى ~/.openclaw/logs/stability/openclaw-stability-*.json عندما يحتوي المسجل على أحداث. افحص أحدث حزمة باستخدام openclaw gateway stability --bundle latest؛ وتنطبق --limit و--type و--since-seq على مخرجات الحزمة أيضًا.

​
gateway diagnostics export

كتابة ملف zip لتشخيصات محلية مصمم لتقارير الأخطاء. للاطلاع على نموذج الخصوصية ومحتويات الحزمة، راجع تصدير التشخيصات.
​
string
مسار ملف zip الناتج. القيمة الافتراضية هي تصدير دعم ضمن دليل الحالة.
​
number
افتراضي:"5000"
الحد الأقصى لأسطر السجل المنقّحة التي سيتم تضمينها.
​
number
افتراضي:"1000000"
الحد الأقصى لبايتات السجل التي سيتم فحصها.
​
string
عنوان URL لـ WebSocket الخاص بـ Gateway من أجل لقطة السلامة.
​
string
رمز Gateway المميز من أجل لقطة السلامة.
​
string
كلمة مرور Gateway من أجل لقطة السلامة.
​
number
افتراضي:"3000"
مهلة لقطة الحالة/السلامة.
​
boolean
تخطّي البحث عن حزمة الاستقرار المحفوظة.
​
boolean
طباعة المسار المكتوب والحجم والبيان بصيغة JSON.
يجمع التصدير في حزمة: manifest.json (قائمة الملفات)، وsummary.md (ملخص Markdown)، وdiagnostics.json (ملخص عالي المستوى للإعدادات/السجلات/الاكتشاف/الاستقرار/الحالة/السلامة)، وconfig/sanitized.json، وstatus/gateway-status.json، وhealth/gateway-health.json، وlogs/openclaw-sanitized.jsonl، وstability/latest.json عند وجود حزمة. صُمم هذا التصدير ليكون قابلاً للمشاركة. فهو يحتفظ بالتفاصيل التشغيلية المفيدة لتصحيح الأخطاء — حقول السجل الآمنة، وأسماء الأنظمة الفرعية، ورموز الحالة، والمدد، والأوضاع المضبوطة، والمنافذ، ومعرّفات Plugin/المزوّد، وإعدادات الميزات غير السرية، ورسائل السجل التشغيلية المنقّحة — ويحذف أو ينقّح نصوص المحادثات، ونصوص طلبات Webhook، ومخرجات الأدوات، وبيانات الاعتماد، وملفات تعريف الارتباط، ومعرّفات الحسابات/الرسائل، ونصوص المطالبات/التعليمات، وأسماء المضيفين، والقيم السرية. عندما تبدو رسالة سجل كنص حمولة لمستخدم/محادثة/أداة (مثل “قال المستخدم” أو “نص المحادثة” أو “مخرجات الأداة” أو “نص طلب Webhook”)، لا يحتفظ التصدير إلا بالإشارة إلى حذف رسالة وعدد بايتاتها.

​
gateway status

يعرض خدمة Gateway ‏(launchd/systemd/schtasks) إلى جانب اختبار اختياري للاتصال/المصادقة.
​
string
إضافة هدف اختبار صريح. يستمر أيضًا اختبار الهدف البعيد المضبوط وlocalhost.
​
string
المصادقة بالرمز المميز للاختبار.
​
string
المصادقة بكلمة المرور للاختبار.
​
number
افتراضي:"10000"
مهلة الاختبار.
​
boolean
تخطّي اختبار الاتصال (عرض الخدمة فقط).
​
boolean
فحص الخدمات على مستوى النظام أيضًا.
​
boolean
ترقية اختبار الاتصال إلى اختبار قراءة والخروج برمز غير صفري إذا فشل. لا يمكن دمجه مع --no-probe.
  • يظل متاحًا للتشخيص حتى عند فقدان إعدادات CLI المحلية أو عدم صلاحيتها.
  • يثبت الناتج الافتراضي حالة الخدمة، واتصال WebSocket، وإمكانية المصادقة الظاهرة وقت المصافحة — وليس عمليات القراءة/الكتابة/الإدارة.
  • لا تغيّر الاختبارات شيئًا في مصادقة الجهاز للمرة الأولى: فهي تعيد استخدام رمز جهاز مميز مخزّن مؤقتًا عند وجوده، لكنها لا تنشئ أبدًا هوية جهاز CLI جديدة أو سجل إقران للقراءة فقط لمجرد التحقق من الحالة.
  • يحل مراجع SecretRef للمصادقة المضبوطة لاستخدامها في مصادقة الاختبار متى أمكن. إذا تعذّر حل SecretRef مطلوب، يُبلغ --json عن rpc.authWarning عند فشل اتصال/مصادقة الاختبار؛ مرّر --token/--password صراحةً أو أصلح مصدر السر. تُحجب تحذيرات تعذّر حل المصادقة بمجرد نجاح الاختبار.
  • يتضمن ناتج JSON الحقل gateway.version عندما يُبلغ عنه Gateway قيد التشغيل؛ ويمكن لـ --require-rpc الرجوع إلى حمولة RPC المسماة status.runtimeVersion إذا تعذّر على اختبار المصافحة توفير بيانات تعريف الإصدار.
  • استخدم --require-rpc في البرامج النصية/الأتمتة عندما لا تكفي خدمة تستمع للاتصالات وتحتاج أيضًا إلى سلامة RPC بنطاق القراءة.
  • يفحص --deep عمليات تثبيت launchd/systemd/schtasks إضافية؛ وعند العثور على عدة خدمات شبيهة بـ Gateway، يطبع الناتج البشري تلميحات للتنظيف (يُشغّل عادةً Gateway واحد لكل جهاز) ويُبلغ عن تسليم حديث لإعادة التشغيل من المشرف عند انطباق ذلك.
  • يشغّل --deep أيضًا التحقق من صحة الإعدادات في وضع مدرك للـ Plugin ‏(pluginValidation: "full") ويُظهر تحذيرات بيان Plugin (مثل فقدان بيانات تعريف إعدادات القناة). يحافظ gateway status الافتراضي على مسار القراءة فقط السريع الذي يتخطى التحقق من صحة Plugin.
  • يتضمن الناتج البشري مسار ملف السجل بعد حله، إلى جانب مسارات إعدادات CLI مقابل الخدمة وصلاحيتها، للمساعدة في تشخيص انحراف ملف التعريف أو دليل الحالة.
  • تقرأ عمليات التحقق من انحراف مصادقة الخدمة كلاً من Environment= وEnvironmentFile= من الوحدة (بما يشمل %h والمسارات المقتبسة والملفات المتعددة وملفات - الاختيارية).
  • تحل مراجع SecretRef الخاصة بـ gateway.auth.token باستخدام بيئة وقت التشغيل المدمجة (بيئة أمر الخدمة أولاً، ثم الرجوع إلى بيئة العملية).
  • تتخطى عمليات التحقق من انحراف الرمز المميز حل رمز الإعدادات عندما لا تكون مصادقة الرمز المميز مفعّلة فعليًا (gateway.auth.mode مضبوط صراحةً على password/none/trusted-proxy، أو الوضع غير مضبوط في حالة إمكانية تغلّب كلمة المرور وعدم إمكانية تغلّب أي رمز مميز مرشح).

​
gateway probe

أمر «تصحيح كل شيء». يختبر دائمًا:
  • Gateway البعيد المضبوط لديك (إن كان مضبوطًا)، و
  • local loopback، حتى إذا كان الهدف البعيد مضبوطًا.
تؤدي إضافة --url إلى وضع ذلك الهدف الصريح قبل كليهما. يضع الناتج البشري التسميات URL (صريح)، وبعيد (مضبوط) / بعيد (مضبوط، غير نشط)، وlocal loopback على الأهداف.
إذا أمكن الوصول إلى عدة أهداف اختبار، فستُطبع جميعها. يمكن لنفق SSH وعنوان URL لـ TLS/الوكيل وعنوان URL البعيد المضبوط أن تشير جميعًا إلى Gateway نفسه حتى مع اختلاف منافذ النقل؛ ويُحجز multiple_gateways لبوابات Gateway مميزة يمكن الوصول إليها أو ملتبسة الهوية. يُدعم تشغيل عدة بوابات Gateway لملفات تعريف معزولة (مثل روبوت إنقاذ)، لكن معظم عمليات التثبيت تشغّل Gateway واحدًا.
​
number
استخدام هذا المنفذ لهدف اختبار local loopback والمنفذ البعيد لنفق SSH. من دون --url، يحدد هذا هدف local loopback فقط بدلاً من عنوان URL لبيئة Gateway المضبوطة أو منفذ البيئة أو الأهداف البعيدة.
  • يعني يمكن الوصول: نعم أن هدفًا واحدًا على الأقل قبل اتصال WebSocket.
  • يُبلغ الإمكانية: للقراءة فقط|قابل للكتابة|قابل للإدارة|الإقران معلّق|اتصال فقط عما استطاع الاختبار إثباته بشأن المصادقة، بمعزل عن إمكانية الوصول.
  • يعني اختبار القراءة: ناجح أن استدعاءات RPC التفصيلية بنطاق القراءة (health/status/system-presence/config.get) نجحت أيضًا.
  • يعني اختبار القراءة: محدود - النطاق مفقود: operator.read أن الاتصال نجح، لكن RPC بنطاق القراءة محدود. يُبلغ عنه كإمكانية وصول متدهورة، وليس فشلاً كاملاً.
  • يعني اختبار القراءة: فشل بعد الاتصال: ناجح أن WebSocket اتصل، لكن مهلة تشخيصات القراءة اللاحقة انتهت أو فشلت — وهذا أيضًا تدهور وليس تعذّر وصول.
  • على غرار gateway status، يعيد الاختبار استخدام مصادقة الجهاز المخزنة مؤقتًا، لكنه لا ينشئ هوية جهاز أو حالة إقران للمرة الأولى.
  • يكون رمز الخروج غير صفري فقط عندما لا يمكن الوصول إلى أي هدف تم اختباره.
المستوى الأعلى:
  • ok: يمكن الوصول إلى هدف واحد على الأقل.
  • degraded: قبل هدف واحد على الأقل اتصالاً، لكنه لم يُكمل تشخيصات RPC التفصيلية بالكامل.
  • capability: أفضل إمكانية شوهدت عبر الأهداف التي يمكن الوصول إليها (read_only أو write_capable أو admin_capable أو pairing_pending أو connected_no_operator_scope أو unknown).
  • primaryTargetId: أفضل هدف للتعامل معه بوصفه الفائز النشط، بالترتيب: عنوان URL الصريح، ثم نفق SSH، ثم الهدف البعيد المضبوط، ثم local loopback.
  • warnings[]: سجلات تحذير بأفضل جهد ممكن، تتضمن code وmessage وtargetIds اختياريًا.
  • network: تلميحات عناوين URL لـ local loopback/tailnet مشتقة من الإعدادات الحالية وشبكة المضيف.
  • discovery.timeoutMs / discovery.count: ميزانية الاكتشاف الفعلية/عدد النتائج المستخدم في دورة الاختبار هذه.
لكل هدف (targets[].connect): ‏ok (إمكانية الوصول + تصنيف التدهور)، وrpcOk (نجاح RPC التفصيلي بالكامل)، وscopeLimited (فشل RPC التفصيلي بسبب فقدان نطاق المشغّل).لكل هدف (targets[].auth): ‏role وscopes المبلغ عنهما في hello-ok عند توفرهما، بالإضافة إلى تصنيف capability الظاهر.
  • ssh_tunnel_failed: فشل إعداد نفق SSH؛ رجع الأمر إلى الاختبارات المباشرة.
  • multiple_gateways: أمكن الوصول إلى هويات Gateway مميزة، أو تعذّر على OpenClaw إثبات أن الأهداف التي يمكن الوصول إليها هي Gateway نفسه. لا يؤدي نفق SSH أو عنوان URL للوكيل أو عنوان URL بعيد مضبوط يشير إلى Gateway نفسه إلى تشغيل هذا التحذير.
  • auth_secretref_unresolved: تعذّر حل SecretRef للمصادقة المضبوطة لهدف فاشل.
  • probe_scope_limited: نجح اتصال WebSocket، لكن اختبار القراءة كان محدودًا بسبب فقدان operator.read.
  • local_tls_runtime_unavailable: تمكين TLS المحلي لـ Gateway، لكن تعذّر على OpenClaw تحميل بصمة الشهادة المحلية.

​
الاتصال البعيد عبر SSH (مماثلة تطبيق Mac)

يستخدم وضع “Remote over SSH” في تطبيق macOS إعادة توجيه منفذ محلي حتى يصبح Gateway البعيد المقيّد بالـ loopback قابلاً للوصول على ws://127.0.0.1:<port>. المكافئ في CLI:
​
string
user@host أو user@host:port (القيمة الافتراضية للمنفذ هي 22).
​
string
ملف الهوية.
​
boolean
اختيار أول مضيف Gateway مكتشف كهدف SSH من نقطة نهاية الاكتشاف المحلولة (local. بالإضافة إلى نطاق الشبكة الواسعة المضبوط، إن وجد). تُتجاهل التلميحات التي تحتوي على TXT فقط.
الإعدادات الافتراضية (اختيارية): gateway.remote.sshTarget، وgateway.remote.sshIdentity.

​
gateway call <method>

أداة مساعدة منخفضة المستوى لـ RPC.
​
string
افتراضي:"{}"
سلسلة كائن JSON للمعلمات.
​
string
عنوان URL لـ WebSocket الخاص بـ Gateway.
​
string
رمز Gateway المميز.
​
string
كلمة مرور Gateway.
​
number
افتراضي:"10000"
ميزانية المهلة.
​
boolean
يُستخدم أساسًا لاستدعاءات RPC بنمط الوكيل التي تدفق أحداثًا وسيطة قبل الحمولة النهائية.
​
boolean
ناتج JSON قابل للقراءة آليًا.
يجب أن تكون قيمة --params بصيغة JSON صالحة، وتتحقق كل طريقة من بنية معلماتها الخاصة (تُرفض الحقول الزائدة أو ذات الأسماء غير الصحيحة).

​
إدارة خدمة Gateway

​
التثبيت باستخدام مغلّف

استخدم --wrapper عندما يجب أن تبدأ الخدمة المُدارة من خلال ملف تنفيذي آخر، مثل وسيط لمدير أسرار أو أداة مساعدة للتشغيل باسم مستخدم آخر. يتلقى المغلّف وسائط Gateway المعتادة، ويكون مسؤولاً عن تنفيذ openclaw أو Node في النهاية باستخدام تلك الوسائط.
يمكنك أيضًا تعيين الغلاف عبر البيئة. يتحقق gateway install من أن المسار ملف قابل للتنفيذ، ويكتب الغلاف في ProgramArguments الخاصة بالخدمة، ويحفظ OPENCLAW_WRAPPER في بيئة الخدمة لعمليات إعادة التثبيت القسرية والتحديثات وإصلاحات الطبيب اللاحقة.
لإزالة غلاف محفوظ، امسح OPENCLAW_WRAPPER أثناء إعادة التثبيت:
  • gateway status: --url، --token، --password، --timeout، --no-probe، --require-rpc، --deep، --json
  • gateway install: --port، --runtime <node|bun> (الافتراضي: node)، --token، --wrapper <path>، --force، --json
  • gateway restart: --safe، --skip-deferral، --force، --wait <duration>، --json
  • gateway uninstall|start: --json
  • gateway stop: --disable، --json
  • استخدم gateway restart لإعادة تشغيل خدمة مُدارة. لا تسلسل gateway stop وgateway start كبديل لإعادة التشغيل.
  • على macOS، يستخدم gateway stop افتراضيًا launchctl bootout، ما يزيل LaunchAgent من جلسة الإقلاع الحالية دون حفظ حالة تعطيل — يظل الاسترداد التلقائي عبر KeepAlive نشطًا للأعطال المستقبلية، ويعيد gateway start التمكين بصورة سليمة دون تنفيذ launchctl enable يدويًا. مرّر --disable لمنع KeepAlive وRunAtLoad بصورة دائمة كي لا يعاود Gateway التشغيل حتى تنفيذ gateway start صراحةً في المرة التالية؛ استخدم هذا عندما ينبغي أن يستمر الإيقاف اليدوي بعد عمليات إعادة الإقلاع.
  • تقبل أوامر دورة الحياة --json للاستخدام في البرمجة النصية.
  • عندما تتطلب مصادقة الرمز المميز رمزًا مميزًا وتكون gateway.auth.token مُدارة بواسطة SecretRef، يتحقق gateway install من إمكانية حل SecretRef، لكنه لا يحفظ الرمز المميز الذي جرى حله في بيانات تعريف بيئة الخدمة.
  • إذا كانت مصادقة الرمز المميز تتطلب رمزًا مميزًا وتعذر حل SecretRef المكوّنة للرمز المميز، يفشل التثبيت بصورة مغلقة بدلًا من حفظ نص صريح احتياطي.
  • لمصادقة كلمة المرور في gateway run، فضّل OPENCLAW_GATEWAY_PASSWORD أو --password-file أو gateway.auth.password المدعومة بواسطة SecretRef على --password المضمّنة.
  • في وضع المصادقة المستنتج، لا تخفف OPENCLAW_GATEWAY_PASSWORD المتاحة في الصدفة فقط متطلبات رمز التثبيت؛ استخدم إعدادًا دائمًا (gateway.auth.password أو env في الإعداد) عند تثبيت خدمة مُدارة.
  • إذا كانت كل من gateway.auth.token وgateway.auth.password مكوّنتين وكانت gateway.auth.mode غير معيّنة، يُحظر التثبيت حتى يُعيّن الوضع صراحةً.

​
اكتشاف بوابات Gateway ‏(Bonjour)

يفحص gateway discover إشارات Gateway ‏(_openclaw-gw._tcp).
  • DNS-SD متعدد البث: local.
  • DNS-SD أحادي البث (Bonjour واسع النطاق): اختر نطاقًا (مثال: openclaw.internal.) وأعِدّ DNS منقسمًا + خادم DNS؛ راجع Bonjour.
لا تعلن الإشارة إلا بوابات Gateway التي فُعّل فيها اكتشاف Bonjour (وهو الإعداد الافتراضي). تلميحات TXT في كل إشارة: role (تلميح دور Gateway)، وtransport (تلميح النقل، مثل gateway)، وgatewayPort (منفذ WebSocket، وعادةً 18789)، وtailnetDns (اسم مضيف MagicDNS عند توفره)، وgatewayTls / gatewayTlsSha256 (تمكين TLS + بصمة الشهادة). لا تُنشر sshPort وcliPath إلا في وضع الاكتشاف الكامل (discovery.mdns.mode: "full"؛ الافتراضي هو "minimal"، الذي يحذفهما — وعندئذٍ تستخدم العملاء المنفذ 22 افتراضيًا لأهداف SSH).

​
gateway discover

​
number
افتراضي:"2000"
المهلة الزمنية لكل أمر (التصفح/الحل).
​
boolean
مخرجات قابلة للقراءة آليًا (وتعطّل أيضًا التنسيق/مؤشر التحميل).
أمثلة:
  • يفحص local. بالإضافة إلى النطاق واسع النطاق المكوّن عند تمكينه.
  • تُشتق wsUrl في مخرجات JSON من نقطة نهاية الخدمة التي جرى حلها، وليس من تلميحات TXT وحدها مثل lanHost أو tailnetDns.
  • تتحكم discovery.mdns.mode في نشر sshPort/cliPath على كل من mDNS ضمن local. وDNS-SD واسع النطاق (راجع أعلاه).

​
ذو صلة