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 دون مصادقة (حاجز أمان).
• يطلق SIGUSR1 إعادة تشغيل داخل العملية عندما يكون ذلك مصرحًا به (commands.restart مفعّل افتراضيًا؛ عيّن commands.restart: false لحظر إعادة التشغيل اليدوية، مع بقاء تطبيق/تحديث أداة Gateway/التكوين مسموحًا).
• توقف معالجات SIGINT/SIGTERM عملية gateway، لكنها لا تستعيد أي حالة طرفية مخصصة. إذا لففت CLI باستخدام TUI أو إدخال raw-mode، فاستعد الطرفية قبل الخروج.

• تحتفظ السجلات بالبيانات الوصفية التشغيلية: أسماء الأحداث، والعدادات، وأحجام البايت، وقراءات الذاكرة، وحالة الطابور/الجلسة، وأسماء القنوات/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 صراحة أو حل مصدر السر أولا.
• إذا نجح الفحص، تُكبت تحذيرات مراجع المصادقة غير المحلولة لتجنب النتائج الإيجابية الكاذبة.
• استخدم --require-rpc في السكربتات والأتمتة عندما لا تكفي خدمة تستمع وتحتاج أيضا إلى أن تكون استدعاءات RPC ذات نطاق القراءة سليمة.
• يضيف --deep فحصا بأفضل جهد لتثبيتات launchd/systemd/schtasks الإضافية. عند اكتشاف عدة خدمات شبيهة بالـ Gateway، تطبع المخرجات البشرية تلميحات تنظيف وتحذر من أن معظم الإعدادات ينبغي أن تشغّل Gateway واحدا لكل جهاز.
• يبلّغ --deep أيضا عن تسليم إعادة تشغيل حديث لمشرف Gateway عندما تخرج عملية الخدمة بنظافة لإعادة تشغيل من مشرف خارجي.
• يشغّل --deep التحقق من الإعداد في وضع واعٍ بالـ Plugin (pluginValidation: "full") ويعرض تحذيرات بيان الـ Plugin المكوّنة (على سبيل المثال بيانات تعريف إعداد قناة مفقودة) كي تلتقطها فحوصات سلامة التثبيت والتحديث. يحافظ gateway status الافتراضي على مسار القراءة فقط السريع الذي يتخطى التحقق من الـ Plugin.
• تتضمن المخرجات البشرية مسار سجل الملف المحلول إضافة إلى لقطة لمسارات/صلاحية إعداد CLI مقابل الخدمة للمساعدة في تشخيص انجراف الملف الشخصي أو دليل الحالة.

• في تثبيتات systemd على Linux، تقرأ فحوصات انحراف مصادقة الخدمة قيم 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: كان أكثر من هدف واحد قابلا للوصول؛ هذا غير معتاد إلا إذا كنت تشغّل ملفات شخصية معزولة عمدا، مثل بوت إنقاذ.
• 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 الجاري تشغيله إجراء فحص مسبق لأعمال OpenClaw النشطة وتأجيل إعادة التشغيل حتى يكتمل تسليم الردود وعمليات التشغيل المضمّنة وتشغيلات المهام. لا يمكن دمج --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 غير معيّن، يُحظر التثبيت حتى يُعيّن الوضع صراحةً.