الانتقال إلى المحتوى الرئيسي
استخدم هذه الصفحة لبدء تشغيل اليوم الأول وعمليات اليوم الثاني لخدمة Gateway.

استكشاف الأخطاء المتعمق

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

التكوين

دليل إعداد موجه بالمهام + مرجع التكوين الكامل.

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

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

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

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

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

1

ابدأ Gateway

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force
2

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

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

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

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

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

  • عملية واحدة تعمل دائمًا للتوجيه، ومستوى التحكم، واتصالات القنوات.
  • منفذ واحد متعدد الإرسال لـ:
    • تحكم/RPC عبر WebSocket
    • واجهات HTTP API (/v1/models، /v1/embeddings، /v1/chat/completions، /v1/responses، /tools/invoke)
    • مسارات HTTP الخاصة بـ Plugin، مثل /api/v1/admin/rpc الاختياري
    • Control UI والخطافات
  • وضع الربط الافتراضي: loopback.
  • المصادقة مطلوبة افتراضيًا. تستخدم إعدادات السر المشترك gateway.auth.token / gateway.auth.password (أو OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD)، ويمكن لإعدادات الوكيل العكسي غير القائمة على local 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 API الخاصة بـ Gateway. ‏Admin HTTP RPC (POST /api/v1/admin/rpc) هو مسار Plugin منفصل ومعطل افتراضيًا لأدوات المضيف التي لا يمكنها استخدام WebSocket RPC. راجع Admin HTTP RPC.

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

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

​
أوضاع إعادة التحميل الساخن

gateway.reload.modeالسلوك
offلا إعادة تحميل للتكوين
hotتطبيق التغييرات الآمنة ساخنًا فقط
restartإعادة التشغيل عند تغييرات تتطلب إعادة التحميل
hybrid (افتراضي)تطبيق ساخن عندما يكون آمنًا، وإعادة التشغيل عند الحاجة

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

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor
gateway status --deep مخصص لاكتشاف خدمات إضافي (LaunchDaemons/وحدات نظام systemd/schtasks)، وليس فحص صحة RPC أعمق.

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

ينبغي لمعظم التثبيتات تشغيل Gateway واحد لكل جهاز. يمكن لـ Gateway واحد استضافة عدة وكلاء وقنوات. لا تحتاج إلى عدة بوابات Gateway إلا عندما تريد عمدًا عزلًا أو بوت إنقاذ. فحوصات مفيدة: 
openclaw gateway status --deep
openclaw gateway probe
ما المتوقع:
  • يمكن أن يبلغ 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 فريد
مثال: 
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
إعداد مفصل: /gateway/multiple-gateways.

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

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

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

استخدم التشغيل الخاضع للإشراف للحصول على موثوقية شبيهة بالإنتاج. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
استخدم 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 ويصلح انحراف تكوين الخدمة.

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

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
تتضمن الافتراضيات حالة/تكوينًا معزولين ومنفذ Gateway أساسيًا 19001.

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

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

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

​
الحيوية

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

​
الجاهزية

openclaw gateway status
openclaw channels status --probe
openclaw health

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

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

​
بصمات الفشل الشائعة

التوقيعالمشكلة المحتملة
refusing to bind gateway ... without authربط غير local loopback من دون مسار مصادقة Gateway صالح
another gateway instance is already listening / EADDRINUSEتعارض في المنفذ
Gateway start blocked: set gateway.mode=localتم ضبط الإعدادات على الوضع البعيد، أو ختم الوضع المحلي مفقود من إعدادات تالفة
unauthorized أثناء الاتصالعدم تطابق المصادقة بين العميل وGateway
للحصول على مسارات تشخيص كاملة، استخدم استكشاف أخطاء Gateway وإصلاحها.

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

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

​
ذات صلة