دليل تشغيل Gateway

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

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

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

openclaw gateway status
openclaw status
openclaw 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 الرئيسي وتستخدم حد مصادقة المشغّل الموثوق نفسه كبقية HTTP API الخاصة بـ Gateway.

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

تسجل خدمات 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 قبل تشغيل التحقق في وقت التشغيل. أضف أي أصول متصفح بعيدة، مثل عناوين وكيل HTTPS، إلى gateway.controlUi.allowedOrigins صراحة.

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

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

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 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 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.

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

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

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

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

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

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

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) قبل المتابعة.

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

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

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

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

ذات صلة:

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

# ذات صلة

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