​

دليل تشغيل خدمة Gateway

تشخيصات تبدأ من الأعراض مع سلاسل أوامر دقيقة وتواقيع السجلات.

​

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

openclaw gateway --port 18789
# for full debug/trace logs in stdio:
openclaw gateway --port 18789 --verbose
# if the port is busy, terminate listeners then start:
openclaw gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch

Linux: `openclaw-gateway-<profile>.service`

openclaw channels status --probe

​

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

• عملية واحدة تعمل دائمًا للتوجيه، ومستوى التحكم، واتصالات القنوات.
• تعدد الإرسال على منفذ واحد.
  • WebSocket للتحكم/RPC
  • OpenResponses (HTTP): /v1/responses.
  • واجهة تحكم ويب وخطافات
• وضع الربط الافتراضي: loopback.
• يتطلب توثيق Gateway افتراضيًا: اضبط gateway.auth.token (أو OPENCLAW_GATEWAY_TOKEN) أو gateway.auth.password.

​

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

​

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

​

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

openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow

​

الوصول عن بُعد

ssh -N -L 18789:127.0.0.1:18789 user@host

​

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

openclaw --profile main gateway install
openclaw --profile rescue gateway install

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

sudo loginctl enable-linger youruser

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

​

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

• 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

​

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

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
# then target the dev instance:
openclaw --dev status
openclaw --dev health

​

البروتوكول (منظور المشغّل)

• يجب أن يكون أول إطار من العميل هو connect.
• يعيد Gateway لقطة hello-ok (presence، health، stateVersion، uptimeMs، الحدود/السياسة).
• الطلبات: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
• الأحداث الشائعة: connect.challenge، agent، chat، presence، tick، health، heartbeat، shutdown.

1. إقرار فوري بالقبول (status:"accepted")
2. استجابات agent على مرحلتين: أولًا تأكيد res {runId,status:"accepted"}، ثم res {runId,status:"ok"|"error",summary} النهائي بعد انتهاء التشغيل؛ ويصل الخرج المتدفق كـ event:"agent".

​

فحوصات تشغيلية

​

التحقق من الحيوية (Liveness)

• الحيوية: افتح WS وأرسل req:connect → توقّع res مع payload.type="hello-ok" (مع لقطة).
• توقّع استجابة hello-ok مع لقطة (snapshot).

​

الجاهزية

`openclaw gateway health|status` — طلب الصحة/الحالة عبر WS الخاص بـ Gateway.

​

استعادة الفجوات

​

أنماط الأعطال الشائعة

​

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

• لا يوجد مسار بديل لاتصالات Baileys المباشرة؛ إذا كانت Gateway متوقفة، تفشل عمليات الإرسال سريعًا.
• تُرفَض الإطارات الأولى غير المتصلة أو JSON المشوّه ويُغلق المقبس.
• إيقاف رشيق: بث حدث shutdown قبل الإغلاق؛ يجب على العملاء التعامل مع الإغلاق + إعادة الاتصال.

• Troubleshooting
• Background Process
• Configuration
• Health
• Doctor
• Authentication