Skip to main content
استخدم هذه الصفحة لبدء تشغيل خدمة Gateway في اليوم الأول ولعملياتها التشغيلية في اليوم الثاني.

استكشاف الأخطاء وإصلاحها بعمق

تشخيصات تبدأ بالأعراض، مع تسلسلات أوامر دقيقة وبصمات للسجلات.

التهيئة

دليل إعداد موجّه نحو المهام + مرجع كامل للتهيئة.

إدارة الأسرار

عقد SecretRef، وسلوك لقطة وقت التشغيل، وعمليات الترحيل/إعادة التحميل.

عقد خطة الأسرار

قواعد الهدف/المسار الدقيقة لـ secrets apply وسلوك ملف تعريف المصادقة المعتمد على المراجع فقط.

​
بدء التشغيل المحلي خلال 5 دقائق

1

بدء Gateway

2

التحقق من سلامة الخدمة

خط الأساس السليم: Runtime: running وConnectivity probe: ok وسطر Capability يطابق ما تتوقعه. استخدم openclaw gateway status --require-rpc لإثبات RPC ضمن نطاق القراءة، وليس لمجرد إثبات إمكانية الوصول.
3

التحقق من جاهزية القنوات

عندما يكون Gateway قابلًا للوصول، يشغّل هذا فحوصات مباشرة للقنوات لكل حساب وعمليات تدقيق اختيارية. إذا تعذّر الوصول إلى Gateway، تعود CLI إلى ملخصات القنوات المستندة إلى التهيئة فقط.
تراقب إعادة تحميل تهيئة Gateway مسار ملف التهيئة النشط (المستخرج من الإعدادات الافتراضية لملف التعريف/الحالة، أو OPENCLAW_CONFIG_PATH عند تعيينه). الوضع الافتراضي هو gateway.reload.mode="hybrid". بعد أول تحميل ناجح، تخدم العملية الجارية لقطة التهيئة النشطة في الذاكرة؛ وتستبدل إعادة التحميل الناجحة تلك اللقطة ذريًا.

​
نموذج وقت التشغيل

  • عملية واحدة دائمة التشغيل للتوجيه ومستوى التحكم واتصالات القنوات.
  • منفذ واحد متعدد الإرسال من أجل:
    • التحكم/RPC عبر WebSocket
    • واجهات HTTP البرمجية (/v1/models و/v1/embeddings و/v1/chat/completions و/v1/responses و/tools/invoke)
    • مسارات HTTP الخاصة بالـ Plugin، مثل /api/v1/admin/rpc الاختياري
    • واجهة التحكم والخطافات
  • وضع الربط الافتراضي: loopback. داخل بيئة حاوية مكتشفة، يكون الإعداد الافتراضي الفعلي هو auto (يُحل إلى 0.0.0.0 لإعادة توجيه المنافذ)، ما لم يكن عرض/نفق Tailscale نشطًا، إذ يفرض دائمًا loopback.
  • المصادقة مطلوبة افتراضيًا. تستخدم إعدادات السر المشترك gateway.auth.token / gateway.auth.password (أو OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) ويمكن لإعدادات الوكيل العكسي غير المرتبطة بعنوان loopback استخدام gateway.auth.mode: "trusted-proxy".

​
نقاط نهاية متوافقة مع OpenAI

سطح التوافق الأعلى تأثيرًا في OpenClaw:
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
أهمية هذه المجموعة:
  • تتحقق معظم تكاملات Open WebUI وLobeChat وLibreChat من /v1/models أولًا.
  • تتوقع كثير من مسارات RAG والذاكرة وجود /v1/embeddings.
  • تفضّل العملاء المصممة أصلًا للوكلاء /v1/responses بصورة متزايدة.
صُمّم /v1/models للوكلاء أولًا: فهو يعيد openclaw وopenclaw/default وopenclaw/<agentId> لكل وكيل تمت تهيئته. يُعد openclaw/default الاسم المستعار الثابت الذي يرتبط دائمًا بالوكيل الافتراضي المهيأ. أرسل x-openclaw-model عندما تريد تجاوز موفّر/نموذج الواجهة الخلفية؛ وإلا يبقى النموذج العادي وإعداد التضمين للوكيل المحدد هما المتحكّمين. تعمل جميع هذه العناصر على منفذ Gateway الرئيسي وتستخدم حد مصادقة المشغّل الموثوق نفسه الذي تستخدمه بقية واجهة HTTP البرمجية لـ Gateway. يُعد RPC الإداري عبر HTTP ‏(POST /api/v1/admin/rpc) مسار Plugin منفصلًا ومعطّلًا افتراضيًا لأدوات المضيف التي لا يمكنها استخدام RPC عبر WebSocket. راجع RPC الإداري عبر HTTP.

​
أسبقية المنفذ والربط

تسجّل خدمات Gateway المثبّتة قيمة --port التي تم حلها ضمن بيانات المشرف الوصفية. بعد تغيير gateway.port، شغّل openclaw doctor --fix أو openclaw gateway install --force كي تبدأ launchd/systemd/schtasks العملية على المنفذ الجديد. يستخدم بدء تشغيل Gateway المنفذ الفعلي والربط نفسيهما عند تهيئة أصول واجهة التحكم المحلية لعمليات الربط غير المرتبطة بعنوان loopback. على سبيل المثال، يهيّئ --bind lan --port 3000 القيمتين http://localhost:3000 وhttp://127.0.0.1:3000 قبل تشغيل التحقق في وقت التشغيل. أضف صراحةً أي أصول لمتصفحات بعيدة، مثل عناوين URL لوكيل HTTPS، إلى gateway.controlUi.allowedOrigins.

​
أوضاع إعادة التحميل الفوري

​
مجموعة أوامر المشغّل

يُستخدم gateway status --deep لاكتشاف خدمات إضافية (LaunchDaemons/وحدات نظام systemd/schtasks)، وليس لإجراء فحص سلامة RPC أعمق.

​
بوابات Gateway متعددة (على المضيف نفسه)

ينبغي لمعظم عمليات التثبيت تشغيل Gateway واحد لكل جهاز. يمكن لـ Gateway واحد استضافة عدة وكلاء وقنوات. لا تحتاج إلى عدة بوابات Gateway إلا عندما تريد عمدًا العزل أو روبوت إنقاذ. فحوصات مفيدة:
ما يمكن توقعه:
  • يمكن لـ gateway status --deep الإبلاغ عن Other gateway-like services detected (best effort) وطباعة تلميحات التنظيف عندما تظل عمليات تثبيت launchd/systemd/schtasks القديمة موجودة.
  • يمكن لـ gateway probe التحذير من multiple reachable gateway identities عندما تستجيب بوابات Gateway مختلفة، أو عندما يتعذر على OpenClaw إثبات أن الأهداف القابلة للوصول هي Gateway نفسه. يُعد نفق SSH أو عنوان URL لوكيل أو عنوان URL بعيد مهيأ إلى Gateway نفسه بوابة Gateway واحدة ذات وسائل نقل متعددة، حتى عندما تختلف منافذ النقل.
  • إذا كان ذلك مقصودًا، فاعزل المنافذ والتهيئة/الحالة وجذور مساحات العمل لكل Gateway.
قائمة تحقق لكل مثيل:
  • gateway.port فريد
  • OPENCLAW_CONFIG_PATH فريد
  • OPENCLAW_STATE_DIR فريد
  • agents.defaults.workspace فريد
مثال:
الإعداد التفصيلي: /gateway/multiple-gateways.

​
الوصول عن بُعد

المفضّل: Tailscale/VPN. الخيار الاحتياطي: نفق SSH.
ثم صِل العملاء محليًا بـ ws://127.0.0.1:18789.
لا تتجاوز أنفاق SSH مصادقة Gateway. بالنسبة إلى مصادقة السر المشترك، يجب على العملاء مع ذلك إرسال token/password حتى عبر النفق. أما في الأوضاع الحاملة للهوية، فيظل على الطلب استيفاء مسار المصادقة ذاك.
راجع: Gateway البعيد، والمصادقة، وTailscale.

​
الإشراف ودورة حياة الخدمة

استخدم عمليات التشغيل الخاضعة للإشراف لتحقيق موثوقية شبيهة ببيئة الإنتاج.
استخدم openclaw gateway restart لعمليات إعادة التشغيل. لا تسلسل openclaw gateway stop وopenclaw gateway start باعتبارهما بديلًا لإعادة التشغيل.على macOS، يستخدم gateway stop القيمة launchctl bootout افتراضيًا. يؤدي ذلك إلى إزالة LaunchAgent من جلسة الإقلاع الحالية دون حفظ حالة التعطيل، بحيث يظل الاسترداد التلقائي عبر KeepAlive يعمل بعد الأعطال غير المتوقعة، ويعيد gateway start التمكين بصورة سليمة. لمنع إعادة التشغيل التلقائي بصورة دائمة عبر عمليات إعادة الإقلاع، مرّر --disable: ‏openclaw gateway stop --disable.تكون تسميات LaunchAgent هي ai.openclaw.gateway (افتراضي) أو ai.openclaw.<profile> (ملف تعريف مسمّى). يدقّق openclaw doctor انحراف تهيئة الخدمة ويصلحه.
تنتهي أخطاء التهيئة غير الصالحة بالرمز 78. تستخدم وحدات systemd في Linux القيمة RestartPreventExitStatus=78 لإيقاف إعادة التشغيل حتى إصلاح التهيئة. لا تتضمن launchd وWindows Task Scheduler قاعدة مكافئة للإيقاف بحسب رمز الخروج، لذلك يحتفظ Gateway أيضًا بسجل عمليات الإقلاع السريعة غير النظيفة ويمنع البدء التلقائي لحسابات القنوات/الموفّرين بعد تكرار إخفاقات بدء التشغيل. في ذلك الوضع الآمن، يظل مستوى التحكم قيد التشغيل للفحص والإصلاح، وترفض عمليات إعادة تحميل التهيئة الفورية وsecrets.reload عمليات إعادة تشغيل القنوات تلقائيًا، ويمكن لطلب صريح من المشغّل عبر channels.start تجاوز المنع.

​
مسار سريع لملف تعريف التطوير

تتضمن الإعدادات الافتراضية حالة/تهيئة معزولتين ومنفذ Gateway أساسيًا بقيمة 19001.

​
مرجع سريع للبروتوكول (منظور المشغّل)

  • يجب أن يكون إطار العميل الأول هو connect.
  • يعيد Gateway إطار hello-ok يتضمن snapshot ‏(presence، health، stateVersion، uptimeMs) بالإضافة إلى حدود policy ‏(maxPayload، maxBufferedBytes، tickIntervalMs).
  • يمثل hello-ok.features.methods / events قائمة استكشاف متحفظة، وليس تفريغًا مولّدًا لكل مسار مساعد قابل للاستدعاء.
  • الطلبات: req(method, params) → res(ok/payload|error).
  • تشمل الأحداث الشائعة connect.challenge، وagent، وchat، وsession.message، وsession.operation، وsession.tool، والأحداث الاختيارية session.approval، وsessions.changed، وpresence، وtick، وhealth، وheartbeat، وأحداث دورة حياة الاقتران/الموافقة، وshutdown.
تُنفَّذ عمليات الوكيل على مرحلتين:
  1. إقرار فوري بالقبول (status:"accepted")
  2. استجابة الإكمال النهائية (status:"ok"|"error")، مع بث أحداث agent بينهما.
راجع وثائق البروتوكول الكاملة: بروتوكول Gateway.

​
فحوص التشغيل

​
التحقق من بقاء الخدمة

  • افتح اتصال WS وأرسل connect.
  • توقّع استجابة hello-ok تتضمن لقطة للحالة.

​
التحقق من الجاهزية

​
الاسترداد من الفجوات

لا تُعاد أحداث البث. عند وجود فجوات في التسلسل، حدّث الحالة (health، system-presence) قبل المتابعة.

​
مؤشرات الأعطال الشائعة

للاطلاع على مسارات التشخيص الكاملة، استخدم استكشاف أخطاء Gateway وإصلاحها.

​
ضمانات السلامة

  • تفشل عملاء بروتوكول Gateway فورًا عند عدم توفر Gateway (من دون رجوع ضمني إلى قناة مباشرة).
  • تُرفض الإطارات الأولى غير الصالحة أو التي لا تمثل اتصالًا، ويُغلق الاتصال.
  • يرسل الإيقاف الآمن حدث shutdown قبل إغلاق المقبس.

​
ذو صلة