Clawdbot Gateway

نظرة عامة على Clawdbot Gateway

Clawdbot Gateway هي العملية الدائمة التي تمتلك اتصالات المراسلة (WhatsApp عبر Baileys، Telegram عبر grammY، Discord، Slack، والمزيد) ومستوى التحكم/الأحداث. إنها الخدمة الأساسية التي تحافظ على تشغيل مساعد Clawdbot AI الخاص بك على مدار الساعة.

ما هو Gateway؟

Gateway هو عملية خفية طويلة الأمد تقوم بـ:

• الحفاظ على جميع اتصالات مزودي المراسلة
• عرض WebSocket API مكتوب للطلبات والردود وأحداث الدفع من الخادم
• التحقق من صحة الإطارات الواردة مقابل JSON Schema
• إرسال أحداث مثل agent، chat، presence، health، heartbeat، cron

المبدأ الأساسي: Gateway واحد لكل مضيف؛ إنه المكان الوحيد الذي يفتح جلسات المراسلة (مثل WhatsApp).

البدء السريع

تشغيل Gateway

clawdbot gateway --port 18789

للحصول على سجلات تصحيح/تتبع كاملة:

clawdbot gateway --port 18789 --verbose

إذا كان المنفذ مشغولاً، أنهِ المستمعين ثم ابدأ:

clawdbot gateway --force

وضع التطوير

للتطوير مع إعادة التحميل التلقائي عند تغييرات TypeScript:

pnpm gateway:watch

هندسة Gateway

المكونات

تدفق الاتصال

Client                    Gateway
  |                          |
  |---- req:connect -------->|
  |<------ res (ok) ---------|
  |                          |
  |<------ event:presence ---|
  |<------ event:tick -------|
  |                          |
  |------- req:agent ------->|
  |<------ res:agent --------|
  |<------ event:agent ------|

تكوين Gateway

التكوين الأساسي

موقع ملف التكوين: ~/.clawdbot/clawdbot.json

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token"
    },
    "reload": {
      "mode": "hybrid"
    }
  }
}

تكوين المنفذ

أولوية المنفذ:

1. علم CLI --port
2. متغير البيئة CLAWDBOT_GATEWAY_PORT
3. gateway.port في التكوين
4. الافتراضي: 18789

المصادقة

مصادقة Gateway مطلوبة افتراضياً. اضبطها عبر:

• gateway.auth.token في التكوين
• متغير البيئة CLAWDBOT_GATEWAY_TOKEN
• gateway.auth.password للمصادقة القائمة على كلمة المرور

يجب على العملاء إرسال connect.params.auth.token أو connect.params.auth.password.

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

إعادة تحميل التكوين السريع تراقب ~/.clawdbot/clawdbot.json:

خدمات Gateway

نقاط نهاية HTTP

يقدم Gateway نقاط نهاية HTTP متعددة على نفس المنفذ:

Canvas Host

يبدأ افتراضياً على المنفذ 18793، يقدم:

http://<gateway-host>:18793/__clawdbot__/canvas/

من ~/.clawdbot/workspace/canvas. للتعطيل:

• canvasHost.enabled: false
• CLAWDBOT_SKIP_CANVAS_HOST=1

لوحة التحكم

الوصول إلى واجهة التحكم على:

http://127.0.0.1:18789/

أو تشغيل:

clawdbot dashboard

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

نفق SSH (موصى به)

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

ثم يتصل العملاء بـ ws://127.0.0.1:18789 عبر النفق.

Tailscale/VPN

مفضل للوصول عن بُعد في الإنتاج. نفس المصافحة + رمز المصادقة ينطبق.

إدارة Gateway

أوامر الخدمة

# التحقق من الحالة
clawdbot gateway status

# فحص الصحة
clawdbot health

# تدقيق الأمان
clawdbot security audit --deep

# إيقاف gateway
clawdbot gateway stop

الإشراف

macOS: يستخدم LaunchAgent (bot.molt.<profile>)

Linux: يستخدم خدمة مستخدم systemd (clawdbot-gateway-<profile>.service)

Windows: يستخدم Windows Service (Clawdbot Gateway (<profile>))

بوابات متعددة

عادةً غير ضرورية—يمكن لـ Gateway واحد خدمة قنوات ووكلاء متعددين. استخدم بوابات متعددة فقط لـ:

• التكرار
• العزل الصارم (مثل، روبوت الإنقاذ)

المتطلبات:

• عزل الحالة + التكوين
• استخدام منافذ فريدة

بروتوكول Wire

النقل

• WebSocket مع إطارات نصية تحتوي على حمولات JSON
• يجب أن يكون الإطار الأول connect

أنواع الرسائل

الطلبات:

{"type": "req", "id": "...", "method": "...", "params": {...}}

الردود:

{"type": "res", "id": "...", "ok": true, "payload": {...}}

الأحداث:

{"type": "event", "event": "...", "payload": {...}, "seq": 1}

التكرار

مفاتيح التكرار مطلوبة للطرق ذات الآثار الجانبية (send، agent) لإعادة المحاولة بأمان.

استكشاف الأخطاء وإصلاحها

Gateway لا يبدأ

1. تحقق مما إذا كان المنفذ قيد الاستخدام: lsof -i :18789
2. راجع السجلات: cat /tmp/clawdbot/gateway.log
3. استخدم --force لإنهاء المستمعين الحاليين

مشاكل الاتصال

1. تحقق من تطابق رمز المصادقة
2. تحقق من اتصال الشبكة
3. راجع سجلات مصافحة WebSocket مع --verbose

مشاكل القناة

1. تحقق من حالة القناة: clawdbot channels status
2. أعد مصادقة القنوات: clawdbot channels login
3. راجع السجلات الخاصة بالقناة

أفضل الممارسات

1. استخدم رموز المصادقة: دائماً قم بتكوين gateway.auth.token للأمان
2. راقب الصحة: تحقق بانتظام من clawdbot health
3. استخدم الإشراف: دع launchd/systemd يدير إعادة التشغيل
4. انسخ التكوين احتياطياً: احتفظ بنسخ احتياطية من ~/.clawdbot/clawdbot.json
5. راجع السجلات: تحقق من السجلات بانتظام للمشاكل

الخطوات التالية

• دليل إعداد Clawdbot - دليل التثبيت الكامل
• تكامل WhatsApp مع Clawdbot - الاتصال بـ WhatsApp
• تكامل Telegram مع Clawdbot - الاتصال بـ Telegram