​

دليل تشغيل البوابة

​

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

openclaw gateway --port 18789
# عكس debug/trace إلى stdio
openclaw gateway --port 18789 --verbose
# اقتل المستمع على المنفذ المحدد بالقوة، ثم ابدأ
openclaw gateway --force

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

​

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

• عملية واحدة دائمة التفعيل للتوجيه، ومستوى التحكم، واتصالات القنوات.
• منفذ واحد متعدد الإرسال من أجل:
  • التحكم/RPC عبر WebSocket
  • HTTP APIs، متوافقة مع 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)، ويمكن لإعدادات reverse-proxy غير المعتمدة على loopback استخدام gateway.auth.mode: "trusted-proxy".

​

نقاط النهاية المتوافقة مع OpenAI

• 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 عندما تريد تجاوز موفّر/نموذج الخلفية؛ وإلا يظل إعداد النموذج والتضمين العادي الخاص بالوكيل المحدد هو المتحكم.

​

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

​

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

​

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

openclaw gateway status
openclaw gateway status --deep   # يضيف فحص خدمة على مستوى النظام
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

​

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

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 عندما يجيب أكثر من هدف واحد.
• إذا كان ذلك مقصودًا، فاعزل المنافذ، والإعداد/الحالة، وجذور مساحة العمل لكل بوابة.

​

الوصول البعيد

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

​

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

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

​

بوابات متعددة على مضيف واحد

• 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
openclaw --dev status

​

مرجع البروتوكول السريع (منظور المشغّل)

• يجب أن يكون أول إطار عميل هو connect.
• تعيد البوابة لقطة hello-ok (presence, health, stateVersion, uptimeMs, limits/policy).
• 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 بينهما.

​

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

​

التوفر

• افتح WS وأرسل connect.
• توقّع استجابة hello-ok مع لقطة.

​

الجاهزية

openclaw gateway status
openclaw channels status --probe
openclaw health

​

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

​

تواقيع الإخفاق الشائعة

​

ضمانات الأمان

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

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