OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

Gateway

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

اكتشاف Bonjour

إعداد mDNS المحلي وDNS-SD واسع النطاق.
نظرة عامة على الاكتشاف

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

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

تشغيل Gateway

bash
openclaw gatewayopenclaw gateway run   # صيغة صريحة مكافئة
سلوك بدء التشغيل
  • يرفض البدء ما لم يُضبط 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 أو إدخال في الوضع الخام، فاستعد الطرفية بنفسك قبل الخروج.

الخيارات

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> منفذ WebSocket (الافتراضي من الإعداد/متغيرات البيئة؛ عادةً 18789).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tYmluZCA8bW9kZQ " type="string"> وضع الربط: loopback (الافتراضي)، وlan، وtailnet، وauto، وcustom.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdG9rZW4gPHRva2Vu " type="string"> الرمز المميز المشترك لـ connect.params.auth.token. تكون القيمة الافتراضية OPENCLAW_GATEWAY_TOKEN عند ضبطه.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tYXV0aCA8bW9kZQ " type="string"> وضع المصادقة: none، وtoken، وpassword، وtrusted-proxy.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcGFzc3dvcmQgPHBhc3N3b3Jk " type="string"> كلمة المرور لـ --auth password.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdGFpbHNjYWxlIDxtb2Rl " type="string"> إتاحة Tailscale:‏ off، وserve، وfunnel.

--tailscale-reset-on-exitboolean

إعادة ضبط إعداد serve/funnel الخاص بـ Tailscale عند الإيقاف.

--allow-unconfiguredboolean

البدء دون فرض gateway.mode=local. للتمهيد المخصص/التطويري فقط؛ ولا يحفظ الإعداد أو يصلحه.

--devboolean

إنشاء إعداد تطويري + مساحة عمل إذا كانا مفقودين (يتخطى BOOTSTRAP.md).

--resetboolean

إعادة ضبط إعداد التطوير وبيانات الاعتماد والجلسات ومساحة العمل. يتطلب --dev.

--forceboolean

إنهاء أي مستمع موجود على المنفذ المستهدف قبل البدء.

--verboseboolean

تسجيل مفصّل إلى stdout/stderr.

--cli-backend-logsboolean

عرض سجلات الواجهة الخلفية لـ CLI فقط في وحدة التحكم (ويفعّل أيضًا stdout/stderr).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0td3MtbG9nIDxzdHlsZQ " type="string" default="auto"> نمط سجل WebSocket:‏ auto، وfull، وcompact.

--compactboolean

اسم مستعار لـ --ws-log compact.

--raw-streamboolean

تسجيل أحداث تدفق النموذج الخام في 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

bash
openclaw gateway restartopenclaw gateway restart --safeopenclaw gateway restart --safe --skip-deferralopenclaw gateway restart --forceopenclaw gateway restart --wait 30s

يطلب --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 العادي (دون خيارات) على سلوك إعادة التشغيل الحالي لمدير الخدمة.

تحليل أداء 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 <url>: عنوان URL لـ WebSocket الخاص بـ Gateway.
  • --token <token>: الرمز المميز لـ Gateway.
  • --password <password>: كلمة مرور Gateway.
  • --timeout <ms>: المهلة/الميزانية (تختلف القيمة الافتراضية حسب الأمر؛ راجع كل أمر أدناه).
  • --expect-final: انتظار استجابة "نهائية" (استدعاءات الوكيل).

gateway health

bash
openclaw gateway health --url ws://127.0.0.1:18789openclaw gateway health --port 18789

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

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> استهداف Gateway محلي عبر local loopback على هذا المنفذ. يتجاوز OPENCLAW_GATEWAY_URL وOPENCLAW_GATEWAY_PORT لهذا الاستدعاء.

gateway usage-cost

جلب ملخصات تكلفة الاستخدام من سجلات الجلسات.

bash
openclaw gateway usage-costopenclaw gateway usage-cost --days 7openclaw gateway usage-cost --agent work --jsonopenclaw gateway usage-cost --all-agentsopenclaw gateway usage-cost --json
"--days
"--agent
--all-agentsboolean

التجميع عبر جميع الوكلاء المُعدّين. لا يمكن الجمع بينه وبين --agent.

gateway stability

جلب مسجل الاستقرار التشخيصي الحديث من Gateway عامل.

bash
openclaw gateway stabilityopenclaw gateway stability --type payload.largeopenclaw gateway stability --bundle latestopenclaw gateway stability --bundle latest --exportopenclaw gateway stability --json

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tbGltaXQgPGxpbWl0 " type="number" default="25"> الحد الأقصى للأحداث الحديثة المراد تضمينها (الحد الأعلى 1000).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdHlwZSA8dHlwZQ " type="string"> التصفية حسب نوع الحدث التشخيصي، مثل payload.large أو diagnostic.memory.pressure.

"--since-seq
--bundle [path]string

قراءة حزمة استقرار محفوظة بدلًا من استدعاء Gateway العامل. يختار --bundle latest (أو --bundle وحده) أحدث حزمة ضمن دليل الحالة؛ ويمكنك أيضًا تمرير مسار JSON للحزمة مباشرةً.

--exportboolean

كتابة ملف zip لتشخيصات الدعم قابل للمشاركة بدلًا من طباعة تفاصيل الاستقرار.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tb3V0cHV0IDxwYXRo " type="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 لتشخيصات محلية مصمم لتقارير الأخطاء. للاطلاع على نموذج الخصوصية ومحتويات الحزمة، راجع تصدير التشخيصات.

bash
openclaw gateway diagnostics exportopenclaw gateway diagnostics export --output openclaw-diagnostics.zipopenclaw gateway diagnostics export --json
"--log-lines
"--log-bytes
"--url
"--token
"--password
"--timeout
--no-stability-bundleboolean

تخطّي البحث عن حزمة الاستقرار المحفوظة.

--jsonboolean

طباعة المسار المكتوب والحجم والبيان بصيغة 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) إلى جانب اختبار اختياري للاتصال/المصادقة.

bash
openclaw gateway statusopenclaw gateway status --jsonopenclaw gateway status --require-rpc
"--url
"--token
"--password
"--timeout
--no-probeboolean

تخطّي اختبار الاتصال (عرض الخدمة فقط).

--deepboolean

فحص الخدمات على مستوى النظام أيضًا.

--require-rpcboolean

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

gateway probe

أمر «تصحيح كل شيء». يختبر دائمًا:

  • Gateway البعيد المضبوط لديك (إن كان مضبوطًا)، و
  • local loopback، حتى إذا كان الهدف البعيد مضبوطًا.

تؤدي إضافة --url إلى وضع ذلك الهدف الصريح قبل كليهما. يضع الناتج البشري التسميات URL (صريح)، وبعيد (مضبوط) / بعيد (مضبوط، غير نشط)، وlocal loopback على الأهداف.

bash
openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --port 18789

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> استخدام هذا المنفذ لهدف اختبار local loopback والمنفذ البعيد لنفق SSH. من دون --url، يحدد هذا هدف local loopback فقط بدلاً من عنوان URL لبيئة Gateway المضبوطة أو منفذ البيئة أو الأهداف البعيدة.

التفسير
  • يعني يمكن الوصول: نعم أن هدفًا واحدًا على الأقل قبل اتصال WebSocket.
  • يُبلغ الإمكانية: للقراءة فقط|قابل للكتابة|قابل للإدارة|الإقران معلّق|اتصال فقط عما استطاع الاختبار إثباته بشأن المصادقة، بمعزل عن إمكانية الوصول.
  • يعني اختبار القراءة: ناجح أن استدعاءات RPC التفصيلية بنطاق القراءة (health/status/system-presence/config.get) نجحت أيضًا.
  • يعني اختبار القراءة: محدود - النطاق مفقود: operator.read أن الاتصال نجح، لكن RPC بنطاق القراءة محدود. يُبلغ عنه كإمكانية وصول متدهورة، وليس فشلاً كاملاً.
  • يعني اختبار القراءة: فشل بعد الاتصال: ناجح أن WebSocket اتصل، لكن مهلة تشخيصات القراءة اللاحقة انتهت أو فشلت — وهذا أيضًا تدهور وليس تعذّر وصول.
  • على غرار gateway status، يعيد الاختبار استخدام مصادقة الجهاز المخزنة مؤقتًا، لكنه لا ينشئ هوية جهاز أو حالة إقران للمرة الأولى.
  • يكون رمز الخروج غير صفري فقط عندما لا يمكن الوصول إلى أي هدف تم اختباره.
ناتج JSON

المستوى الأعلى:

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

bash
openclaw gateway probe --ssh user@gateway-host

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc3NoIDx0YXJnZXQ " type="string"> user@host أو user@host:port (القيمة الافتراضية للمنفذ هي 22).

--ssh-autoboolean

اختيار أول مضيف Gateway مكتشف كهدف SSH من نقطة نهاية الاكتشاف المحلولة (local. بالإضافة إلى نطاق الشبكة الواسعة المضبوط، إن وجد). تُتجاهل التلميحات التي تحتوي على TXT فقط.

الإعدادات الافتراضية (اختيارية): gateway.remote.sshTarget، وgateway.remote.sshIdentity.

gateway call <method>

أداة مساعدة منخفضة المستوى لـ RPC.

bash
openclaw gateway call statusopenclaw gateway call logs.tail --params '{"limit": 200}'
"--params
"--url
"--token
"--password
"--timeout
--expect-finalboolean

يُستخدم أساسًا لاستدعاءات RPC بنمط الوكيل التي تدفق أحداثًا وسيطة قبل الحمولة النهائية.

--jsonboolean

ناتج JSON قابل للقراءة آليًا.

إدارة خدمة Gateway

bash
openclaw gateway installopenclaw gateway startopenclaw gateway stopopenclaw gateway restartopenclaw gateway uninstall

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

استخدم --wrapper عندما يجب أن تبدأ الخدمة المُدارة من خلال ملف تنفيذي آخر، مثل وسيط لمدير أسرار أو أداة مساعدة للتشغيل باسم مستخدم آخر. يتلقى المغلّف وسائط Gateway المعتادة، ويكون مسؤولاً عن تنفيذ openclaw أو Node في النهاية باستخدام تلك الوسائط.

bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'#!/usr/bin/env bashset -euo pipefailexec doppler run --project my-project --config production -- openclaw "$@"EOFchmod +x ~/.local/bin/openclaw-doppler openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --forceopenclaw gateway restart

يمكنك أيضًا تعيين الغلاف عبر البيئة. يتحقق gateway install من أن المسار ملف قابل للتنفيذ، ويكتب الغلاف في ProgramArguments الخاصة بالخدمة، ويحفظ OPENCLAW_WRAPPER في بيئة الخدمة لعمليات إعادة التثبيت القسرية والتحديثات وإصلاحات الطبيب اللاحقة.

bash
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --forceopenclaw doctor

لإزالة غلاف محفوظ، امسح OPENCLAW_WRAPPER أثناء إعادة التثبيت:

bash
OPENCLAW_WRAPPER= openclaw gateway install --forceopenclaw gateway restart
خيارات الأمر
  • 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 للاستخدام في البرمجة النصية.
المصادقة وSecretRefs وقت التثبيت
  • عندما تتطلب مصادقة الرمز المميز رمزًا مميزًا وتكون 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

bash
openclaw gateway discover
"--timeout
--jsonboolean

مخرجات قابلة للقراءة آليًا (وتعطّل أيضًا التنسيق/مؤشر التحميل).

أمثلة:

bash
openclaw gateway discover --timeout 4000openclaw gateway discover --json | jq '.beacons[].wsUrl'

ذو صلة

Was this useful?
On this page

On this page