Gateway

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

• تحتفظ السجلات بالبيانات الوصفية التشغيلية: أسماء الأحداث، والأعداد، وأحجام البايتات، وقراءات الذاكرة، وحالة قائمة الانتظار/الجلسة، ومعرّفات الموافقة، وأسماء القنوات/Plugin، وملخصات الجلسات المنقحة. لا تحتفظ بنص المحادثة، أو أجسام Webhook، أو مخرجات الأدوات، أو أجسام الطلب أو الاستجابة الخام، أو الرموز، أو ملفات تعريف الارتباط، أو القيم السرية، أو أسماء المضيفين، أو معرّفات الجلسات الخام. عيّن diagnostics.enabled: false لتعطيل المسجل بالكامل.
• عند خروج Gateway الفادح، ومهل الإيقاف، وفشل بدء التشغيل بعد إعادة التشغيل، يكتب OpenClaw اللقطة التشخيصية نفسها إلى ~/.openclaw/logs/stability/openclaw-stability-*.json عندما تكون لدى المسجل أحداث. افحص أحدث حزمة باستخدام openclaw gateway stability --bundle latest؛ تنطبق --limit و--type و--since-seq أيضًا على إخراج الحزمة.

• يظل gateway status متاحًا للتشخيص حتى عندما تكون إعدادات CLI المحلية مفقودة أو غير صالحة.
• يثبت gateway status الافتراضي حالة الخدمة واتصال WebSocket وقدرة المصادقة المرئية وقت المصافحة. ولا يثبت عمليات القراءة/الكتابة/الإدارة.
• فحوص التشخيص غير مُغيِّرة لمصادقة الجهاز لأول مرة: فهي تعيد استخدام رمز جهاز مخبأ موجود عند توفره، لكنها لا تنشئ هوية جهاز CLI جديدة أو سجل اقتران جهاز للقراءة فقط لمجرد التحقق من الحالة.
• يحل gateway status مراجع SecretRefs الخاصة بالمصادقة المضبوطة لمصادقة الفحص عندما يكون ذلك ممكنًا.
• إذا تعذر حل SecretRef مطلوب للمصادقة في مسار هذا الأمر، يبلّغ gateway status --json عن rpc.authWarning عند فشل اتصال/مصادقة الفحص؛ مرّر --token/--password صراحةً أو عالج مصدر السر أولًا.
• إذا نجح الفحص، تُكتم تحذيرات مرجع المصادقة غير المحلول لتجنب النتائج الإيجابية الكاذبة.
• عند تفعيل الفحص، يتضمن خرج JSON ‏gateway.version عندما يبلّغ Gateway الجاري عنه؛ يمكن لـ --require-rpc الرجوع إلى حمولة RPC ‏status.runtimeVersion إذا لم يستطع فحص المصافحة اللاحق توفير بيانات تعريف الإصدار.
• استخدم --require-rpc في السكربتات والأتمتة عندما لا تكفي خدمة تستمع وتحتاج أيضًا إلى أن تكون استدعاءات RPC بنطاق القراءة سليمة.
• يضيف --deep فحصًا بأفضل جهد لعمليات تثبيت launchd/systemd/schtasks الإضافية. عند اكتشاف عدة خدمات شبيهة بـ gateway، يطبع الخرج البشري تلميحات تنظيف ويحذر من أن معظم الإعدادات يجب أن تشغّل gateway واحدًا لكل جهاز.
• يبلّغ --deep أيضًا عن تسليم حديث لإعادة تشغيل مشرف Gateway عندما تخرج عملية الخدمة بنظافة لإعادة تشغيل مشرف خارجي.
• يشغّل --deep تحقق الإعدادات في وضع مدرك للـ Plugin ‏(pluginValidation: "full") ويعرض تحذيرات بيان Plugin المضبوط (مثل غياب بيانات تعريف إعدادات القناة) حتى تلتقطها فحوص تثبيت وتحديث smoke. يحافظ gateway status الافتراضي على مسار القراءة فقط السريع الذي يتخطى تحقق Plugin.
• يتضمن الخرج البشري مسار ملف السجل المحلول مع لقطة مسارات/صلاحية إعدادات CLI مقابل الخدمة للمساعدة في تشخيص انحراف الملف الشخصي أو دليل الحالة.

• في عمليات تثبيت Linux systemd، تقرأ فحوص انحراف مصادقة الخدمة قيم Environment= وEnvironmentFile= من الوحدة (بما في ذلك %h، والمسارات المقتبسة، والملفات المتعددة، وملفات - الاختيارية).
• تحل فحوص الانحراف مراجع SecretRefs الخاصة بـ gateway.auth.token باستخدام بيئة التشغيل المدمجة (بيئة أمر الخدمة أولًا، ثم بيئة العملية كرجوع احتياطي).
• إذا لم تكن مصادقة الرمز فعالة فعليًا (gateway.auth.mode صريح بقيمة password/none/trusted-proxy، أو الوضع غير مضبوط حيث يمكن لكلمة المرور أن تفوز ولا يمكن لأي مرشح رمز أن يفوز)، تتخطى فحوص انحراف الرمز حل رمز الإعدادات.

• يعني Reachable: yes أن هدفًا واحدًا على الأقل قبل اتصال WebSocket.
• يبلّغ Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only عما استطاع الفحص إثباته بشأن المصادقة. وهذا منفصل عن قابلية الوصول.
• يعني Read probe: ok أن استدعاءات RPC التفصيلية بنطاق القراءة (health/status/system-presence/config.get) نجحت أيضًا.
• يعني Read probe: limited - missing scope: operator.read أن الاتصال نجح لكن RPC بنطاق القراءة محدود. يُبلَّغ عن ذلك كقابلية وصول متدهورة، وليس فشلًا كاملًا.
• يعني Read probe: failed بعد Connect: ok أن Gateway قبل اتصال WebSocket، لكن تشخيصات القراءة اللاحقة انتهت مهلتها أو فشلت. وهذا أيضًا قابلية وصول متدهورة، وليس Gateway غير قابل للوصول.
• مثل 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: دور المصادقة المبلّغ عنه في hello-ok عند توفره.
• 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.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --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 الصريح التالي؛ استخدم هذا عندما يجب أن يستمر الإيقاف اليدوي بعد عمليات إعادة الإقلاع أو إعادة تشغيل النظام.
• يطلب gateway restart --safe من Gateway الجاري إجراء فحص مسبق للعمل النشط وجدولة إعادة تشغيل واحدة مدمجة بعد انتهاء العمل النشط. تنتظر إعادة التشغيل الآمنة الافتراضية العمل النشط حتى مدة gateway.reload.deferralTimeoutMs المضبوطة (الافتراضي 5 دقائق)؛ وعند انتهاء تلك المهلة تُفرض إعادة التشغيل. عيّن gateway.reload.deferralTimeoutMs إلى 0 لانتظار آمن غير محدد لا يفرض أبدًا. لا يمكن دمج --safe مع --force أو --wait.
• يتجاوز gateway restart --wait 30s ميزانية انتظار تصريف إعادة التشغيل المضبوطة لتلك الإعادة. الأرقام المجردة هي بالمللي ثانية؛ وتُقبل وحدات مثل s وm وh. ينتظر --wait 0 إلى أجل غير محدد.
• يشغل gateway restart --safe --skip-deferral إعادة التشغيل الآمنة المدركة لـ OpenClaw لكنه يتجاوز بوابة التأجيل بحيث يصدر Gateway إعادة التشغيل فورًا حتى عند الإبلاغ عن عوائق. هذا مخرج طارئ للمشغل لتأجيلات تشغيل المهام العالقة؛ ويتطلب --safe.
• يتخطى gateway restart --force تصريف العمل النشط ويعيد التشغيل فورًا. استخدمه عندما يكون المشغل قد فحص بالفعل عوائق المهام المدرجة ويريد عودة Gateway الآن.
• تقبل أوامر دورة الحياة --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 غير معين، يُحظر التثبيت حتى يُعيّن الوضع صراحةً.