الانتقال إلى المحتوى الرئيسي

​
دليل تشغيل Gateway

استخدم هذه الصفحة لبدء التشغيل في اليوم الأول وعمليات التشغيل في اليوم الثاني لخدمة 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 وRPC probe: ok.
3

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

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

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

  • عملية واحدة تعمل دائمًا للتوجيه ومستوى التحكم واتصالات القنوات.
  • منفذ واحد متعدد الإرسال من أجل:
    • WebSocket للتحكم/RPC
    • واجهات HTTP API متوافقة مع OpenAI (/v1/models و/v1/embeddings و/v1/chat/completions و/v1/responses و/tools/invoke)
    • Control UI وhooks
  • وضع الربط الافتراضي: 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 API الخاصة بـ Gateway.

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

الإعدادترتيب التحديد
منفذ Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
وضع الربطCLI/override → gateway.bind → loopback

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

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 system وschtasks)، وليس لفحص سلامة RPC أعمق.

​
عدة Gateways (على المضيف نفسه)

يجب أن تشغّل معظم عمليات التثبيت Gateway واحدًا لكل جهاز. يمكن لـ Gateway واحد استضافة عدة وكلاء وقنوات. تحتاج إلى عدة Gateways فقط عندما تريد العزل عمدًا أو روبوت إنقاذ. فحوصات مفيدة: 
openclaw gateway status --deep
openclaw gateway probe
ما الذي يجب توقعه:
  • يمكن أن يبلّغ gateway status --deep عن Other gateway-like services detected (best effort) ويعرض تلميحات تنظيف عندما تظل تثبيتات launchd/systemd/schtasks القديمة موجودة.
  • يمكن أن يحذّر gateway probe من multiple reachable gateways عندما يستجيب أكثر من هدف واحد.
  • إذا كان ذلك مقصودًا، فاعزل المنافذ والإعدادات/الحالة وجذور مساحة العمل لكل Gateway.
إعداد مفصل: /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
تسميات LaunchAgent هي ai.openclaw.gateway (الافتراضي) أو ai.openclaw.<profile> (ملف شخصي مسمّى). يقوم openclaw doctor بتدقيق انجراف إعدادات الخدمة وإصلاحه.

​
عدة Gateways على مضيف واحد

يجب أن تشغّل معظم الإعدادات Gateway واحدًا. استخدم عدة Gateways فقط للعزل/الاستمرارية الصارمة (على سبيل المثال ملف إنقاذ). قائمة التحقق لكل نسخة:
  • 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
راجع: عدة Gateways.

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

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.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ربط غير loopback من دون مسار مصادقة صالح لـ Gateway
another gateway instance is already listening / EADDRINUSEتعارض منفذ
Gateway start blocked: set gateway.mode=localالإعداد مضبوط على الوضع البعيد، أو ختم الوضع المحلي مفقود من إعداد تالف
unauthorized during connectعدم تطابق المصادقة بين العميل وGateway
للاطلاع على سلاسل تشخيص كاملة، استخدم استكشاف أخطاء Gateway.

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

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