الانتقال إلى المحتوى الرئيسي
Gateway هو خادم WebSocket الخاص بـ OpenClaw (القنوات، العُقد، الجلسات، الخطافات). توجد الأوامر الفرعية في هذه الصفحة ضمن openclaw gateway ….

اكتشاف Bonjour

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

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

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

الإعدادات

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

​
تشغيل Gateway

شغّل عملية Gateway محلية: 
openclaw gateway
اسم مستعار للتشغيل في الواجهة الأمامية: 
openclaw gateway run
  • افتراضيًا، يرفض 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 أو إدخال بوضع خام، فاستعد الطرفية قبل الخروج.

​
الخيارات

​
--port <port>
number
منفذ WebSocket (تأتي القيمة الافتراضية من الإعدادات/البيئة؛ عادةً 18789).
​
--bind <loopback|lan|tailnet|auto|custom>
string
وضع ربط المستمع. يتم حاليًا حل lan وtailnet وcustom عبر مسارات تعمل بـ IPv4 فقط.
​
--auth <token|password>
string
تجاوز وضع المصادقة.
​
--token <token>
string
تجاوز الرمز المميز (يعيّن أيضًا OPENCLAW_GATEWAY_TOKEN للعملية).
​
--password <password>
string
تجاوز كلمة المرور.
​
--password-file <path>
string
قراءة كلمة مرور Gateway من ملف.
​
--tailscale <off|serve|funnel>
string
عرض Gateway عبر Tailscale.
​
--tailscale-reset-on-exit
boolean
إعادة تعيين إعداد Tailscale serve/funnel عند إيقاف التشغيل.
​
--bind custom + gateway.customBindHost
string
يتوقع عنوان IPv4 اليوم. بالنسبة إلى BYOH المعتمد على IPv6 فقط، ضع مكوّنًا جانبيًا أو وكيلًا لـ IPv4 أمام Gateway ووجّه OpenClaw إلى نقطة نهاية IPv4 تلك.
​
--allow-unconfigured
boolean
السماح ببدء Gateway دون gateway.mode=local في الإعدادات. يتجاوز حاجز بدء التشغيل للتمهيد المؤقت/التطويري فقط؛ ولا يكتب ملف الإعدادات أو يصلحه.
​
--dev
boolean
إنشاء إعداد تطوير + مساحة عمل إذا كانا مفقودين (يتخطى BOOTSTRAP.md).
​
--reset
boolean
إعادة تعيين إعداد التطوير + بيانات الاعتماد + الجلسات + مساحة العمل (يتطلب --dev).
​
--force
boolean
إنهاء أي مستمع موجود على المنفذ المحدد قبل البدء.
​
--verbose
boolean
سجلات مفصلة.
​
--cli-backend-logs
boolean
إظهار سجلات الواجهة الخلفية لـ CLI فقط في وحدة التحكم (وتفعيل stdout/stderr).
​
--ws-log <auto|full|compact>
string
افتراضي:"auto"
نمط سجل WebSocket.
​
--compact
boolean
اسم مستعار لـ --ws-log compact.
​
--raw-stream
boolean
تسجيل أحداث تدفق النموذج الخام إلى jsonl.
​
--raw-stream-path <path>
string
مسار jsonl للتدفق الخام.

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

openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --safe --skip-deferral
openclaw gateway restart --force
يطلب openclaw gateway restart --safe من Gateway العامل إجراء فحص تمهيدي للعمل النشط وجدولة إعادة تشغيل واحدة مدمجة بعد تصريف العمل النشط. تنتظر إعادة التشغيل الآمنة الافتراضية العمل النشط حتى مدة gateway.reload.deferralTimeoutMs المضبوطة (الافتراضي 5 دقائق)؛ وعند انتهاء تلك الميزانية تُفرض إعادة التشغيل. عيّن gateway.reload.deferralTimeoutMs إلى 0 لانتظار آمن غير محدد لا يفرض أبدًا. يحافظ restart العادي على سلوك مدير الخدمة الحالي؛ ويظل --force مسار التجاوز الفوري. يشغّل openclaw gateway restart --safe --skip-deferral إعادة التشغيل المنسقة نفسها الواعية بـ OpenClaw مثل --safe، لكنه يتجاوز بوابة تأجيل العمل النشط بحيث يصدر Gateway إعادة التشغيل فورًا حتى عند الإبلاغ عن عوائق. استخدمه كمخرج طوارئ للمشغّل عندما يكون التأجيل مثبتًا بسبب تشغيل مهمة عالق وقد يكون --safe وحده مقيدًا بـ gateway.reload.deferralTimeoutMs. يتطلب --skip-deferral الخيار --safe.
قد تظهر --password المضمنة في قوائم العمليات المحلية. فضّل --password-file أو البيئة أو gateway.auth.password مدعومًا بـ SecretRef.

​
تحليل أداء Gateway

  • عيّن OPENCLAW_GATEWAY_STARTUP_TRACE=1 لتسجيل توقيتات المراحل أثناء بدء Gateway، بما في ذلك تأخير 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 لقياس إعادة تشغيل Gateway داخل العملية مقابل مدخل CLI المبني على macOS أو Linux. يستخدم قياس إعادة التشغيل SIGUSR1، ويفعّل تتبعي بدء التشغيل وإعادة التشغيل في العملية الفرعية، ويسجل /healthz التالي، و/readyz التالي، ووقت التعطل، وتوقيت الجاهزية، وCPU، وRSS، ومقاييس تتبع إعادة التشغيل.
  • تعامل مع /healthz كمؤشر حياة و/readyz كجاهزية قابلة للاستخدام. أسطر التتبع ومخرجات القياس مخصصة لإسناد الملكية؛ لا تعتبر امتداد تتبع واحدًا أو عينة واحدة استنتاجًا كاملًا عن الأداء.

​
الاستعلام عن Gateway قيد التشغيل

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

​
gateway health

openclaw gateway health --url ws://127.0.0.1:18789
openclaw gateway health --port 18789
نقطة نهاية HTTP /healthz هي مسبار حياة: تعود بمجرد أن يستطيع الخادم الإجابة عبر HTTP. نقطة نهاية HTTP /readyz أكثر صرامة وتظل حمراء بينما لا تزال مكونات Plugin الجانبية عند بدء التشغيل أو القنوات أو الخطافات المضبوطة في طور الاستقرار. تتضمن استجابات الجاهزية التفصيلية المحلية أو المصادق عليها كتلة تشخيص eventLoop مع تأخير حلقة الأحداث، واستخدام حلقة الأحداث، ونسبة أنوية CPU، وعلامة degraded.
​
--port <port>
number
استهدف local loopback Gateway على هذا المنفذ. يتجاوز هذا OPENCLAW_GATEWAY_URL وOPENCLAW_GATEWAY_PORT لاستدعاء الصحة.

​
gateway usage-cost

اجلب ملخصات تكلفة الاستخدام من سجلات الجلسات. 
openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --agent work --json
openclaw gateway usage-cost --all-agents
openclaw gateway usage-cost --json
​
--days <days>
number
افتراضي:"30"
عدد الأيام المراد تضمينها.
​
--agent <id>
string
حصر ملخص التكلفة في معرّف وكيل واحد مضبوط.
​
--all-agents
boolean
تجميع ملخص التكلفة عبر جميع الوكلاء المضبوطين. لا يمكن دمجه مع --agent.

​
gateway stability

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

​
gateway diagnostics export

اكتب ملف zip محليًا للتشخيصات مصممًا لإرفاقه بتقارير الأخطاء. لنموذج الخصوصية ومحتويات الحزمة، راجع تصدير التشخيصات. 
openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json
​
--output <path>
string
مسار ملف zip الناتج. يكون افتراضيًا تصدير دعم ضمن دليل الحالة.
​
--log-lines <count>
number
افتراضي:"5000"
الحد الأقصى لأسطر السجل المنقّاة المطلوب تضمينها.
​
--log-bytes <bytes>
number
افتراضي:"1000000"
الحد الأقصى لبايتات السجل المطلوب فحصها.
​
--url <url>
string
عنوان URL الخاص بـ Gateway WebSocket للقطة السلامة.
​
--token <token>
string
رمز Gateway للقطة السلامة.
​
--password <password>
string
كلمة مرور Gateway للقطة السلامة.
​
--timeout <ms>
number
افتراضي:"3000"
مهلة لقطة الحالة/السلامة.
​
--no-stability-bundle
boolean
تخطَّ البحث عن حزمة الاستقرار المحفوظة.
​
--json
boolean
اطبع المسار المكتوب والحجم والبيان بصيغة JSON.
يحتوي التصدير على بيان وملخص Markdown وشكل الإعدادات وتفاصيل إعدادات منقّاة وملخصات سجلات منقّاة ولقطات حالة/سلامة Gateway منقّاة وأحدث حزمة استقرار عند وجودها. الغرض منه هو مشاركته. يحتفظ بتفاصيل تشغيلية تساعد في التصحيح، مثل حقول سجلات OpenClaw الآمنة وأسماء الأنظمة الفرعية ورموز الحالة والمدد والأوضاع المضبوطة والمنافذ ومعرّفات Plugin ومعرّفات المزوّدين وإعدادات الميزات غير السرية ورسائل السجل التشغيلية المنقّحة. ويحذف أو ينقّح نصوص المحادثات ونصوص webhook ومخرجات الأدوات وبيانات الاعتماد وملفات تعريف الارتباط ومعرّفات الحسابات/الرسائل ونصوص المطالبات/التعليمات وأسماء المضيفين والقيم السرية. عندما تبدو رسالة بأسلوب LogTape كنص حمولة مستخدم/محادثة/أداة، يحتفظ التصدير فقط بأن رسالة حُذفت مع عدد بايتاتها.

​
gateway status

يعرض gateway status خدمة Gateway ‏(launchd/systemd/schtasks) مع فحص اختياري لقدرة الاتصال/المصادقة. 
openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
​
--url <url>
string
أضف هدف فحص صريحًا. سيظل فحص الهدف البعيد المضبوط وlocalhost قائمًا.
​
--token <token>
string
مصادقة الرمز للفحص.
​
--password <password>
string
مصادقة كلمة المرور للفحص.
​
--timeout <ms>
number
افتراضي:"10000"
مهلة الفحص.
​
--no-probe
boolean
تخطَّ فحص الاتصال (عرض الخدمة فقط).
​
--deep
boolean
افحص خدمات مستوى النظام أيضًا.
​
--require-rpc
boolean
ارفع فحص الاتصال الافتراضي إلى فحص قراءة واخرج برمز غير صفري عند فشل فحص القراءة هذا. لا يمكن دمجه مع --no-probe.
  • يظل 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، أو الوضع غير مضبوط حيث يمكن لكلمة المرور أن تفوز ولا يمكن لأي مرشح رمز أن يفوز)، تتخطى فحوص انحراف الرمز حل رمز الإعدادات.

​
gateway probe

gateway probe هو أمر “تصحيح كل شيء”. يفحص دائمًا:
  • gateway البعيد المضبوط لديك (إن كان مضبوطًا)، و
  • localhost ‏(local loopback) حتى إذا كان البعيد مضبوطًا.
إذا مرّرت --url، تتم إضافة ذلك الهدف الصريح قبل كليهما. يضع الخرج البشري تسميات للأهداف كالتالي:
  • URL (explicit)
  • Remote (configured) أو Remote (configured, inactive)
  • Local loopback
إذا أمكن الوصول إلى عدة أهداف فحص، يطبعها كلها. يمكن لنفق SSH وعنوان URL الخاص بـ TLS/proxy وعنوان URL البعيد المضبوط أن تشير كلها إلى gateway نفسه حتى عندما تختلف منافذ النقل بينها؛ multiple_gateways مخصص للـ gateways المميزة أو التي يلتبس تمييز هويتها ويمكن الوصول إليها. تُدعم عدة gateways عند استخدام ملفات شخصية معزولة (مثل بوت إنقاذ)، لكن معظم عمليات التثبيت ما زالت تشغّل gateway واحدًا.
openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --port 18789
​
--port <port>
number
استخدم هذا المنفذ لهدف فحص local loopback ومنفذ نفق SSH البعيد. من دون --url، يختار هذا هدف local loopback بدلًا من عنوان URL بيئة gateway المضبوطة أو منفذ البيئة أو الأهداف البعيدة.
  • يعني 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.

​
البعيد عبر SSH (تكافؤ تطبيق Mac)

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

​
gateway call <method>

مساعد RPC منخفض المستوى. 
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
​
--params <json>
string
افتراضي:"{}"
سلسلة كائن JSON للمعاملات.
​
--url <url>
string
عنوان URL الخاص بـ Gateway WebSocket.
​
--token <token>
string
رمز Gateway.
​
--password <password>
string
كلمة مرور Gateway.
​
--timeout <ms>
number
ميزانية المهلة.
​
--expect-final
boolean
أساسًا لاستدعاءات RPC بأسلوب الوكيل التي تبث أحداثًا وسيطة قبل حمولة نهائية.
​
--json
boolean
خرج JSON قابل للقراءة آليًا.
يجب أن يكون --params بصيغة JSON صالحة.

​
إدارة خدمة Gateway

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

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

استخدم --wrapper عندما يجب أن تبدأ الخدمة المُدارة عبر ملف تنفيذي آخر، مثل غلاف مدير الأسرار أو مساعد التشغيل كمستخدم آخر. يتلقى الغلاف وسيطات Gateway العادية ويكون مسؤولًا في النهاية عن تنفيذ openclaw أو Node بتلك الوسيطات. 
cat > ~/.local/bin/openclaw-doppler <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
يمكنك أيضًا تعيين الغلاف من خلال البيئة. يتحقق gateway install من أن المسار ملف قابل للتنفيذ، ويكتب الغلاف في ProgramArguments الخاصة بالخدمة، ويثبت OPENCLAW_WRAPPER في بيئة الخدمة لعمليات إعادة التثبيت القسرية والتحديثات وإصلاحات doctor لاحقًا. 
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor
لإزالة غلاف محفوظ، امسح OPENCLAW_WRAPPER أثناء إعادة التثبيت: 
OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw gateway restart
  • 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 غير معين، يُحظر التثبيت حتى يُعيّن الوضع صراحةً.

​
اكتشاف البوابات (Bonjour)

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

​
gateway discover

openclaw gateway discover
​
--timeout <ms>
number
افتراضي:"2000"
مهلة لكل أمر (تصفح/حل).
​
--json
boolean
إخراج قابل للقراءة آليًا (يعطل أيضًا التنسيق/مؤشر التحميل).
أمثلة: 
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
  • يفحص CLI النطاق local. بالإضافة إلى النطاق واسع النطاق المضبوط عند تفعيله.
  • wsUrl في إخراج JSON مشتق من نقطة نهاية الخدمة المحلولة، وليس من تلميحات TXT فقط مثل lanHost أو tailnetDns.
  • على mDNS للنطاق local. وDNS-SD واسع النطاق، لا يُنشر sshPort وcliPath إلا عندما يكون discovery.mdns.mode هو full.

​
ذات صلة