دليل تشغيل Gateway

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

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

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

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

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

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

تسجل خدمات 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   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

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

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

لا تحتاج إلى عدة Gateways إلا عندما تريد العزل عمدا أو بوت إنقاذ.

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

openclaw gateway status --deepopenclaw gateway probe

ما يمكن توقعه:

• يمكن لـ gateway status --deep الإبلاغ عن Other gateway-like services detected (best effort) وطباعة تلميحات تنظيف عندما تبقى تثبيتات launchd/systemd/schtasks قديمة.
• يمكن لـ gateway probe التحذير من multiple reachable gateways عندما يجيب أكثر من هدف واحد.
• إذا كان ذلك مقصودا، فاعزل المنافذ والإعدادات/الحالة وجذور مساحات العمل لكل 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@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 <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143KillMode=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

المسار السريع لملف التطوير الشخصي

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --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 statusopenclaw channels status --probeopenclaw health

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

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

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

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

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

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

ذات صلة:

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

ذات صلة

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