دليل تشغيل 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 (/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 المحلولة في بيانات المشرف الوصفية. بعد تغيير 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 صراحة.

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

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

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 أعمق.

عدة بوابات 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@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 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

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

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.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 statusopenclaw channels status --probeopenclaw health

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

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

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

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

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

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

ذات صلة:

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

ذات صلة

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