دليل تشغيل Gateway

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

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

openclaw gateway --port 18789# عكس مخرجات التصحيح/التتبّع إلى الإدخال والإخراج القياسيينopenclaw gateway --port 18789 --verbose# إنهاء المستمع بالقوة على المنفذ المحدد، ثم بدء التشغيلopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

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

• عملية واحدة دائمة التشغيل للتوجيه ومستوى التحكم واتصالات القنوات.
• منفذ واحد متعدد الإرسال من أجل:
  • التحكم/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.

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

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

openclaw gateway statusopenclaw gateway status --deep   # يضيف فحصًا للخدمة على مستوى النظامopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

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

ينبغي لمعظم عمليات التثبيت تشغيل Gateway واحد لكل جهاز. يمكن لـ Gateway واحد استضافة عدة وكلاء وقنوات. لا تحتاج إلى عدة بوابات Gateway إلا عندما تريد عمدًا العزل أو روبوت إنقاذ.

فحوصات مفيدة:

openclaw gateway status --deepopenclaw 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 19001OPENCLAW_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@gateway-host

ثم صِل العملاء محليًا بـ ws://127.0.0.1:18789.

راجع: Gateway البعيد، والمصادقة، وTailscale.

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

استخدم عمليات التشغيل الخاضعة للإشراف لتحقيق موثوقية شبيهة ببيئة الإنتاج.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

تنتهي أخطاء التهيئة غير الصالحة بالرمز 78. تستخدم وحدات systemd في Linux القيمة RestartPreventExitStatus=78 لإيقاف إعادة التشغيل حتى إصلاح التهيئة. لا تتضمن launchd وWindows Task Scheduler قاعدة مكافئة للإيقاف بحسب رمز الخروج، لذلك يحتفظ Gateway أيضًا بسجل عمليات الإقلاع السريعة غير النظيفة ويمنع البدء التلقائي لحسابات القنوات/الموفّرين بعد تكرار إخفاقات بدء التشغيل. في ذلك الوضع الآمن، يظل مستوى التحكم قيد التشغيل للفحص والإصلاح، وترفض عمليات إعادة تحميل التهيئة الفورية وsecrets.reload عمليات إعادة تشغيل القنوات تلقائيًا، ويمكن لطلب صريح من المشغّل عبر channels.start تجاوز المنع.

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

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

تتضمن الإعدادات الافتراضية حالة/تهيئة معزولتين ومنفذ 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 تتضمن لقطة للحالة.

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

openclaw gateway statusopenclaw channels status --probeopenclaw health

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

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

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

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

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

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

ذو صلة

• الإعدادات
• استكشاف أخطاء Gateway وإصلاحها
• العملية الخلفية
• الصحة
• Doctor
• المصادقة
• الوصول عن بُعد
• إدارة الأسرار