واجهة HTTP المتوافقة مع OpenAI في OpenClaw

أي شيء يتحدث بروتوكول OpenAI Chat Completions يمكنه التحدث إلى وكيل OpenClaw، لأن gateway يقدّم واجهة متوافقة صغيرة على المنفذ نفسه الذي يستخدمه WebSocket الخاص به. وهي معطّلة افتراضيًا، وتمنح عند تفعيلها وصول مشغّل (operator) كاملًا، وحقلها model يعني شيئًا مختلفًا عمّا يظنه عميلك. إليك العقد كما يصفه التوثيق.

ما الذي تقدّمه ومن الذي تثق به

• بمجرد تفعيل gateway.http.endpoints.chatCompletions، يقدّم gateway على منفذه POST /v1/chat/completions، وGET /v1/models، وGET لمعرّف نموذج واحد، وPOST /v1/embeddings؛ أما نقطة النهاية responses فتُفعَّل بشكل منفصل، وكل طلب يعمل كتشغيل وكيل عادي في gateway على مسار الشيفرة نفسه الذي يستخدمه الأمر agent، لذا يتطابق التوجيه والصلاحيات والإعداد مع gateway لديك.
• رمز gateway أو كلمة مروره الصالحة لنقطة النهاية هذه يعادل بيانات اعتماد مالك أو مشغّل، لا نطاقًا خاصًا بكل مستخدم: فمصادقة bearer بالسر المشترك تتجاهل أي ترويسة x-openclaw-scopes وتستعيد مجموعة نطاقات المشغّل الافتراضية كاملة، وتعامل أدوار الدردشة على أنها أدوار مرسل مالك؛ أما وضع trusted-proxy أو المدخل الخاص بلا مصادقة فيحترم x-openclaw-scopes عند وجودها ويحتاج إلى operator.admin لعناصر التحكم على مستوى المالك.
• تتبع المصادقة وضع gateway: رمز bearer أو كلمة مرور من الإعداد أو من متغير البيئة، أو خادم وسيط (proxy) مدرك للهوية في وضع trusted-proxy (الخوادم الوسيطة على loopback في المضيف نفسه تحتاج إلى allowLoopback)، أو بلا ترويسة على مدخل خاص؛ ويمكن للمستدعين على المضيف نفسه الذين يتجاوزون الخادم الوسيط الموثوق أن يرتدّوا إلى كلمة المرور ما لم تُبقهم أدلة ترويسات التمرير (forwarded) على مسار الخادم الوسيط، وتعيد المحاولات الفاشلة الكثيرة 429 مع Retry-After عند ضبط حد للمعدل.
• يفضّل التوثيق نقطة النهاية هذه على قناة مدمجة جديدة عندما يكون التكامل مجرد واجهة مشغّل أخرى، ويفضّل WebChat أو بروتوكول gateway مع مسار إقران الجهاز لعملاء الهاتف المحمول الأصليين حتى لا يُشحن أي رمز مشترك على الجهاز، ويفضّل مكوّنًا إضافيًا للقنوات عند دمج شبكة مراسلة خارجية لها مستخدموها وغرفها ووسيلة نقلها.

يعامل OpenClaw حقل model في OpenAI كهدف وكيل، لا كمعرّف خام لنموذج مزوّد.

النماذج وكلاء، والجلسات تأتي من user

يوجّه openclaw وopenclaw/default إلى الوكيل الافتراضي المعدّ، ويوجّه ⁨openclaw/⁩ متبوعًا بمعرّف الوكيل، أو agent: متبوعًا به، إلى وكيل محدد، ويسرد ⁨/v1/models⁩ أهداف الوكلاء هذه، لا نماذج المزوّدين ولا الوكلاء الفرعيين. تتجاوز الترويسة x-openclaw-model نموذج الواجهة الخلفية للوكيل المحدد، مباشرةً للمستدعين بالسر المشترك، وفقط مع operator.admin للمستدعين الحاملين لهوية؛ ويوجّه x-openclaw-session-key صراحةً ويُرفض برمز 400 عندما يستخدم مساحة أسماء محجوزة مثل subagent أو cron أو acp؛ ويضبط x-openclaw-message-channel قناة دخول اصطناعية للمطالبات التي تراعي القناة. افتراضيًا، كل طلب عديم الحالة بمفتاح جلسة جديد؛ وتشتق سلسلة user في OpenAI مفتاحًا ثابتًا بحيث تتشارك الاستدعاءات المتكررة جلسة واحدة، لذا أعد استخدام قيمة واحدة لكل سلسلة محادثة وتجنّب المعرّفات على مستوى الحساب ما لم يكن على عدة أجهزة أن تتشارك جلسة واحدة. ومتابعة جلسة incognito صراحةً تتطلب operator.admin فعليًا، والاستجابة المستندة إلى ملف تعريف تُخفي الهدف بخطأ forbidden يظهر كأن الهدف غير موجود.

الأدوات والحدود والبث المتدفق

• أدوات الدوال وtool_choice (auto أو none أو required أو دالة مثبّتة) مدعومة، مع رسائل متابعة بدور tool مرتبطة بواسطة tool_call_id؛ وmax_completion_tokens هو الحد الأقصى الحالي مع max_tokens كاسم مستعار قديم، أما temperature وtop_p ومعاملات العقوبة وseed وما يصل إلى أربع تسلسلات stop فيجري التحقق منها ثم تُمرَّر بأفضل جهد ممكن، وأسماؤها في الطلب المرسل يختارها ناقل المزوّد.
• تقتصر الطلبات على 20 MB لجسم الطلب، و8 أجزاء image_url من آخر رسالة مستخدم، و20 MB من بيانات الصور بعد فك الترميز؛ وتُرفض الصور المأخوذة من عناوين URL ما لم يكن images.allowUrl مفعّلًا، مع قائمة سماح للمضيفين، وأنواع MIME مسموح بها، و10 MB لكل صورة، و3 عمليات إعادة توجيه، ومهلة 10 s افتراضيًا، وتُحوَّل HEIC وHEIF إلى JPEG، ولا يتجاوز اسم المضيف المدرج في قائمة السماح حظر عناوين IP الخاصة أبدًا.
• مع stream بقيمة true تصل الأحداث كسطور data تنتهي بالسطر DONE، وتصل استدعاءات الأدوات كأجزاء delta تدريجية ثم سبب انتهاء tool_calls، ويصل جزء usage عند ضبط include_usage؛ ويعيد التشغيل الفاشل خطأً بدلًا من إكمال، ويُصدر فشل البث المتدفق كائن error ثم DONE، ويؤدي انقطاع اتصال العميل إلى إلغاء تنزيلات المصادر وتشغيل الوكيل.

يتناول مقال واجهة OpenClaw البرمجية واجهة gateway البرمجية على نطاق أوسع، ويشرح مقال نطاقات المشغّل في OpenClaw مجموعة نطاقات المشغّل التي تستعيدها نقطة النهاية هذه أو تضيّقها.

وصفة Open WebUI

الإعداد السريع هو عنوان URL أساسي يتكون من مضيف gateway ومنفذه مع ⁨/v1⁩، وhost.docker.internal من Docker على macOS، ورمز gateway من نوع bearer كمفتاح API، وopenclaw/default كنموذج؛ وإذا أعاد curl على ⁨/v1/models⁩ مع رمز bearer القيمة openclaw/default، فإن معظم إعدادات Open WebUI تتصل بعنوان URL الأساسي والرمز نفسيهما. ثم تعرض الأمثلة جلسة ثابتة بقيمة user تبدأ بالبادئة conv، واستدعاء بث متدفق مع x-openclaw-model يثبّت نموذج مزوّد، وجلب نموذج واحد مع ترميز الشرطة المائلة في URL، والتضمينات (embeddings) مع نموذج تضمين في الترويسة وعدد صحيح dimensions اختياري يتجاوز أبعاد مخرجات ذاكرة الوكيل. ويشرح دليل الوصول عن بُعد إلى OpenClaw كيف تصل إلى المنفذ بأمان، ودليل ضوابط أمان gateway في OpenClaw عناصر التحكم التي تحرسه.

على Diali

على Diali، يقع gateway خلف مدخل المنصة، ويُولَّد إعداد التشغيل من لوحة التحكم، لذا فإن إتاحة هذه الواجهة قرار إعداد وليست منفذًا تفتحه. تصف صفحة OpenClaw المستضاف على Diali المساعد المستضاف، وتعرض صفحة أسعار Diali الخطط التي يأتي ضمنها.

• معطّلة افتراضيًا؛ وعند تفعيلها يصبح الرمز وصول مالك.
• الحقل model يسمّي وكيلًا؛ والحقل user يسمّي الجلسة.
• عبر loopback أو tailnet أو مدخل خاص، لا عبر الإنترنت العام أبدًا.