الانتقال إلى المحتوى الرئيسي

​
استدعاء الأدوات (HTTP)

تُوفّر Gateway في OpenClaw نقطة نهاية HTTP بسيطة لاستدعاء أداة واحدة مباشرة. تكون مُمكّنة دائمًا، لكنها مقيّدة بمصادقة Gateway وسياسة الأدوات.
  • POST /tools/invoke
  • نفس المنفذ المستخدم لـ Gateway (تعدد WS + HTTP): http://<gateway-host>:<port>/tools/invoke
الحد الأقصى الافتراضي لحجم الحمولة هو 2 ميغابايت.

​
المصادقة

تستخدم تهيئة مصادقة Gateway. أرسل رمز Bearer:
  • Authorization: Bearer <token>
ملاحظات:
  • عند gateway.auth.mode="token"، استخدم gateway.auth.token (أو OPENCLAW_GATEWAY_TOKEN).
  • عند gateway.auth.mode="password"، استخدم gateway.auth.password (أو OPENCLAW_GATEWAY_PASSWORD).
  • إذا تم تكوين gateway.auth.rateLimit وحدث عدد كبير جدًا من إخفاقات المصادقة، فستُرجع نقطة النهاية 429 مع Retry-After.

​
طلب الجسم

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}
الحقول:
  • tool (string، مطلوب): اسم الأداة المراد استدعاؤها.
  • action (string، اختياري): يُدرج في args إذا كان مخطط الأداة يدعم action ولم تتضمن حمولة args هذا الحقل.
  • args (object، اختياري): وسائط خاصة بالأداة.
  • sessionKey (string، اختياري): مفتاح الجلسة الهدف. إذا تم إهماله أو كان "main"، تستخدم Gateway مفتاح الجلسة الرئيسي المُهيّأ (مع احترام session.mainKey والوكيل الافتراضي، أو global في النطاق العام).
  • dryRun (boolean، اختياري): محجوز للاستخدام المستقبلي؛ يتم تجاهله حاليًا.

​
السلوك الخاص بالسياسات والتوجيه

تُرشَّح إتاحة الأدوات عبر سلسلة السياسات نفسها المستخدمة بواسطة وكلاء Gateway:
  • tools.profile / tools.byProvider.profile
  • tools.allow / tools.byProvider.allow
  • agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
  • سياسات المجموعات (إذا كان مفتاح الجلسة يطابق مجموعة أو قناة)
  • سياسة الوكيل الفرعي (عند الاستدعاء باستخدام مفتاح جلسة وكيل فرعي)
إذا لم يُسمح بالأداة وفق السياسة، تُعيد نقطة النهاية الرمز 404. يطبق Gateway HTTP أيضًا قائمة حظر صارمة افتراضيًا (حتى لو سمحت سياسة الجلسة بالأداة):
  • sessions_spawn
  • sessions_send
  • gateway
  • whatsapp_login
يمكنك تخصيص قائمة الحظر هذه عبر gateway.tools: 
{
  gateway: {
    tools: {
      // أدوات إضافية لحظرها عبر HTTP /tools/invoke
      deny: ["browser"],
      // إزالة أدوات من قائمة الحظر الافتراضية
      allow: ["gateway"],
    },
  },
}
لمساعدة سياسات المجموعات على حلّ السياق، يمكنك اختياريًا تعيين:
  • x-openclaw-message-channel: <channel> (مثال: slack، telegram)
  • x-openclaw-account-id: <accountId> (عند وجود حسابات متعددة)

​
الاستجابات

  • 200 → { ok: true, result }
  • 400 → { ok: false, error: { type, message } } (طلب غير صالح أو خطأ في الأداة)
  • 401 → غير مُصرّح
  • 429 → تم تقييد المصادقة بسبب تجاوز المعدل (Retry-After مُعيّن)
  • 404 → الأداة غير متاحة (غير موجودة أو غير مُدرجة في قائمة السماح)
  • 405 → الطريقة غير مسموح بها
  • 500 → { ok: false, error: { type, message } } (خطأ غير متوقع أثناء تنفيذ الأداة؛ رسالة منقّحة)

​
مثال

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'