إكمالات الدردشة من OpenAI

يمكن لـ Gateway توفير واجهة صغيرة متوافقة مع OpenAI لإكمالات الدردشة. وهي معطّلة افتراضيًا.

بعد تمكينها، توفّر جميع المسارات التالية على المنفذ نفسه الذي يستخدمه Gateway (تعدد إرسال WS + HTTP):

تُنفَّذ الطلبات كتشغيل عادي لوكيل Gateway (عبر مسار الشفرة نفسه الذي يستخدمه openclaw agent)، لذلك تتطابق آليات التوجيه والأذونات والإعدادات مع Gateway لديك.

تمكين نقطة النهاية

{  gateway: {    http: {      endpoints: {        chatCompletions: { enabled: true },      },    },  },}

عيّن enabled: false (أو احذفه) للتعطيل.

الحد الأمني (مهم)

تعامل مع نقطة النهاية هذه باعتبارها تمنح وصولًا كاملًا للمشغّل إلى مثيل Gateway:

• يُعادل رمز Gateway المميز/كلمة المرور الصالحة لنقطة النهاية هذه بيانات اعتماد المالك/المشغّل، وليس نطاقًا محدودًا لكل مستخدم.
• تمر الطلبات عبر مسار وكيل مستوى التحكم نفسه الذي تستخدمه إجراءات المشغّل الموثوق بها، ولذلك يمكن لنقطة النهاية هذه استخدام الأدوات الحساسة إذا كانت سياسة الوكيل المستهدف تسمح بها.
• أبقِها مقتصرة على local loopback أو الشبكة الطرفية أو الدخول الخاص. لا تعرضها للإنترنت العام.

مصفوفة المصادقة:

راجع نطاقات المشغّل، والأمان، والوصول عن بُعد.

المصادقة

تستخدم إعدادات مصادقة Gateway (راجع مصادقة الوكيل الموثوق للاطلاع على تفاصيل هذا الوضع):

ملاحظات:

• يمكن للمستدعين على المضيف نفسه الذين يتجاوزون الوكيل في Gateway يعمل بوضع trusted-proxy الرجوع مباشرةً إلى gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. ويؤدي وجود أي دليل في ترويسات Forwarded أو X-Forwarded-* أو X-Real-IP إلى إبقاء الطلب على مسار الوكيل الموثوق بدلًا من ذلك.
• إذا تم إعداد gateway.auth.rateLimit وفشلت محاولات مصادقة كثيرة جدًا، فستعيد نقطة النهاية الرمز 429 مع ترويسة Retry-After.

متى تستخدم نقطة النهاية هذه

• فضّلها على إضافة قناة مضمّنة جديدة عندما لا يكون تكاملك سوى واجهة مشغّل/عميل أخرى لـ Gateway نفسه.
• بالنسبة إلى عملاء الأجهزة المحمولة الأصليين الذين يتصلون مباشرةً بـ Gateway بعيد، فضّل WebChat أو بروتوكول Gateway مع تدفق التهيئة الأولية للجهاز المقترن/رمز الجهاز المميز، لكي لا يحتاج الجهاز إلى رمز HTTP مميز/كلمة مرور مشتركة.
• أنشئ Plugin قناة بدلًا من ذلك عند التكامل مع شبكة مراسلة خارجية لها مستخدموها أو غرفها أو تسليم Webhook أو نقلها الصادر. راجع إنشاء Plugins.

عقد النموذج القائم على الوكيل أولًا

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

ترويسات الطلب الاختيارية:

يسرد /v1/models أهداف الوكلاء ذات المستوى الأعلى (openclaw، وopenclaw/default، وopenclaw/<agentId>)، وليس نماذج مزوّدي الواجهة الخلفية ولا الوكلاء الفرعيين؛ إذ يظل الوكلاء الفرعيون جزءًا من بنية التنفيذ الداخلية. وإذا حذفت x-openclaw-model، فسيعمل الوكيل المحدد باستخدام نموذجه المعتاد المُعدّ.

يستخدم /v1/embeddings معرّفات model نفسها الخاصة بأهداف الوكلاء. أرسل x-openclaw-model (من مستدعٍ يستخدم سرًا مشتركًا، أو مستدعٍ يحمل الهوية ولديه operator.admin) لاختيار نموذج تضمين محدد؛ وإلا فسيستخدم الطلب إعداد التضمين المعتاد للوكيل المحدد.

سلوك الجلسة

تكون نقطة النهاية افتراضيًا عديمة الحالة لكل طلب (يتم إنشاء مفتاح جلسة جديد في كل استدعاء).

إذا تضمّن الطلب سلسلة OpenAI باسم user، فسيشتق Gateway منها مفتاح جلسة ثابتًا لكي تتمكن الاستدعاءات المتكررة من مشاركة جلسة وكيل. بالنسبة إلى التطبيقات المخصصة، أعد استخدام قيمة user نفسها لكل سلسلة محادثة؛ وتجنّب المعرّفات على مستوى الحساب إلا إذا أردت أن تشارك عدة محادثات/أجهزة جلسة OpenClaw واحدة. استخدم x-openclaw-session-key فقط عندما تحتاج إلى تحكم صريح في التوجيه عبر عدة عملاء/سلاسل، باستخدام مفاتيح يملكها التطبيق وتتجنب مساحات الأسماء المحجوزة أعلاه.

حدود الطلبات (الإعدادات)

يمكن ضبط القيم الافتراضية ضمن gateway.http.endpoints.chatCompletions:

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          maxBodyBytes: 20000000,          maxImageParts: 8,          maxTotalImageBytes: 20000000,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

القيم الافتراضية عند الحذف:

تُقبل مصادر image_url بتنسيقي HEIC/HEIF وتُطبّع إلى JPEG قبل تسليمها إلى المزوّد عبر معالج الصور المشترك في OpenClaw ‏(Rastermill)، والذي يرجع إلى محوّل نظام (sips أو ImageMagick أو GraphicsMagick أو ffmpeg) للتنسيقات التي تحتاج إلى دعم برنامج ترميز خارجي.

ملاحظة أمنية: لا يؤدي إدراج اسم مضيف في قائمة السماح إلى تجاوز حظر عناوين IP الخاصة/الداخلية. بالنسبة إلى بوابات Gateway المكشوفة للإنترنت، طبّق ضوابط خروج الشبكة بالإضافة إلى وسائل الحماية على مستوى التطبيق. راجع الأمان.

عقد أداة المحادثة

يدعم /v1/chat/completions مجموعة فرعية من أدوات الدوال متوافقة مع عملاء محادثة OpenAI الشائعين.

حقول الطلب المدعومة

تمر جميع حقول أخذ العينات وحدود الرموز عبر قناة معاملات تدفق الوكيل نفسها، وتُمرَّر وفق أفضل جهد ممكن:

• حد الرموز: يختار نقل المزوّد اسم الحقل على السلك: max_completion_tokens لنقاط النهاية من عائلة OpenAI، وmax_tokens للمزوّدين الذين لا يقبلون إلا الاسم القديم (Mistral وChutes).
• يُربط stop بحقل الإيقاف في طبقة النقل: stop للواجهات الخلفية لإكمالات المحادثة، وstop_sequences لـ Anthropic. لا تحتوي واجهة OpenAI Responses API على معامل إيقاف، لذا لا يُطبَّق stop على النماذج المستندة إلى Responses.
• تستخدم الواجهة الخلفية لـ Codex Responses المستندة إلى ChatGPT أخذ عينات ثابتًا من جانب الخادم، وتزيل temperature وtop_p (إلى جانب max_output_tokens وmetadata وprompt_cache_retention وservice_tier) قبل وصول الطلب إلى تلك الواجهة الخلفية.

المتغيرات غير المدعومة

يُعاد 400 invalid_request_error في الحالات التالية:

• إذا لم تكن tools مصفوفة، أو كانت تتضمن إدخالات أدوات ليست دوال، أو كان tool.function.name مفقودًا
• متغيرات tool_choice مثل allowed_tools وcustom
• قيم tool_choice.function.name التي لا تطابق أداة مقدَّمة

بالنسبة إلى tool_choice: "required" وtool_choice المثبّت على دالة، تحصر نقطة النهاية مجموعة أدوات الدوال المعروضة من العميل، وتوجّه وقت التشغيل إلى استدعاء أداة عميل قبل الاستجابة، وتُرجع خطأ إذا لم تتضمن استجابة الوكيل استدعاءً منظمًا مطابقًا لأداة عميل. ينطبق ذلك على قائمة tools التي يوفّرها المستدعي عبر HTTP، وليس على كل أداة داخلية لوكيل OpenClaw.

بنية استجابة الأداة دون بث

عندما يستدعي الوكيل الأدوات، تستخدم الاستجابة ما يلي:

• choices[0].finish_reason = "tool_calls"
• إدخالات choices[0].message.tool_calls[] التي تتضمن id وtype: "function" وfunction.name وfunction.arguments (سلسلة JSON)
• تعليقات المساعد قبل استدعاء الأداة، في choices[0].message.content (وقد تكون فارغة)

بنية استجابة الأداة أثناء البث

عندما تكون stream: true، تصل استدعاءات الأدوات في مقاطع SSE تزايدية: فرق أولي لدور المساعد، ثم فروق اختيارية لتعليقات المساعد، ثم مقطع واحد أو أكثر من delta.tool_calls يحمل هوية الأداة وأجزاء الوسيطات، ثم مقطع نهائي يتضمن finish_reason: "tool_calls" وdata: [DONE].

إذا كانت stream_options.include_usage=true، يُصدر مقطع استخدام أخير قبل [DONE].

حلقة المتابعة للأداة

بعد تلقي tool_calls، نفّذ الدالة أو الدوال المطلوبة وأرسل طلب متابعة يتضمن رسالة استدعاء الأداة السابقة من المساعد، بالإضافة إلى رسالة واحدة أو أكثر ذات role: "tool" وقيمة tool_call_id مطابقة. يواصل ذلك حلقة الاستدلال نفسها للوكيل لإنتاج الإجابة النهائية.

البث (SSE)

عيّن stream: true لتلقي أحداث مرسلة من الخادم:

• Content-Type: text/event-stream
• يكون كل سطر حدث على النحو data: <json>
• ينتهي التدفق بالسطر data: [DONE]

الإعداد السريع لـ Open WebUI

• عنوان URL الأساسي: http://127.0.0.1:18789/v1
• عنوان URL الأساسي لـ Docker على macOS: http://host.docker.internal:18789/v1
• مفتاح API: رمز حامل Gateway الخاص بك
• النموذج: openclaw/default

السلوك المتوقع: يسرد GET /v1/models النموذج openclaw/default، ويستخدمه Open WebUI بوصفه معرّف نموذج المحادثة. لاستخدام مزوّد/نموذج خلفي محدد، عيّن النموذج الافتراضي المعتاد للوكيل، أو أرسل x-openclaw-model (مستدعٍ يملك سرًا مشتركًا، أو مستدعٍ يحمل هوية مع operator.admin).

اختبار تحقق سريع:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

إذا أعاد ذلك openclaw/default، فيمكن لمعظم إعدادات Open WebUI الاتصال باستخدام عنوان URL الأساسي والرمز نفسيهما.

أمثلة

جلسة ثابتة لمحادثة واحدة في تطبيق:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"Summarize my tasks for today"}]  }'

أعِد استخدام قيمة user نفسها في الاستدعاءات اللاحقة لتلك المحادثة لمواصلة جلسة الوكيل نفسها.

دون بث:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "messages": [{"role":"user","content":"hi"}]  }'

مع البث:

curl -N http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/gpt-5.4' \  -d '{    "model": "openclaw/research",    "stream": true,    "messages": [{"role":"user","content":"hi"}]  }'

سرد النماذج:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

جلب نموذج واحد:

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \  -H 'Authorization: Bearer YOUR_TOKEN'

إنشاء تضمينات:

curl -sS http://127.0.0.1:18789/v1/embeddings \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/text-embedding-3-small' \  -d '{    "model": "openclaw/default",    "input": ["alpha", "beta"]  }'

يدعم /v1/embeddings قيمة input كسلسلة أو مصفوفة سلاسل.

ذو صلة

• مرجع الإعدادات
• نطاقات المشغّل
• OpenAI