--- read_when: - دمج الأدوات التي تتوقع واجهة إكمالات المحادثة من OpenAI summary: إتاحة نقطة نهاية HTTP متوافقة مع OpenAI على المسار /v1/chat/completions من Gateway title: إكمالات الدردشة من OpenAI x-i18n: generated_at: "2026-07-12T05:53:46Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 9b1fffd2ce3da881ecd91adbb7c5d10b1d7adbd99af9b2ea4544b62ecbaf1f32 source_path: gateway/openai-http-api.md workflow: 16 --- يمكن لـ Gateway توفير واجهة صغيرة متوافقة مع OpenAI لإكمالات الدردشة. وهي **معطّلة افتراضيًا**. بعد تمكينها، توفّر جميع المسارات التالية على المنفذ نفسه الذي يستخدمه Gateway (تعدد إرسال WS + HTTP): | الطريقة | المسار | | ------- | ---------------------- | | POST | `/v1/chat/completions` | | GET | `/v1/models` | | GET | `/v1/models/{id}` | | POST | `/v1/embeddings` | | POST | `/v1/responses` | تُنفَّذ الطلبات كتشغيل عادي لوكيل Gateway (عبر مسار الشفرة نفسه الذي يستخدمه `openclaw agent`)، لذلك تتطابق آليات التوجيه والأذونات والإعدادات مع Gateway لديك. ## تمكين نقطة النهاية ```json5 { gateway: { http: { endpoints: { chatCompletions: { enabled: true }, }, }, }, } ``` عيّن `enabled: false` (أو احذفه) للتعطيل. ## الحد الأمني (مهم) تعامل مع نقطة النهاية هذه باعتبارها تمنح **وصولًا كاملًا للمشغّل** إلى مثيل Gateway: - يُعادل رمز Gateway المميز/كلمة المرور الصالحة لنقطة النهاية هذه بيانات اعتماد المالك/المشغّل، وليس نطاقًا محدودًا لكل مستخدم. - تمر الطلبات عبر مسار وكيل مستوى التحكم نفسه الذي تستخدمه إجراءات المشغّل الموثوق بها، ولذلك يمكن لنقطة النهاية هذه استخدام الأدوات الحساسة إذا كانت سياسة الوكيل المستهدف تسمح بها. - أبقِها مقتصرة على local loopback أو الشبكة الطرفية أو الدخول الخاص. لا تعرضها للإنترنت العام. مصفوفة المصادقة: | مسار المصادقة | السلوك | | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gateway.auth.mode="token"` أو `"password"` مع `Authorization: Bearer ...` | يثبت حيازة سر Gateway المشترك. يتجاهل أي ترويسة `x-openclaw-scopes` ويستعيد مجموعة نطاقات المشغّل الافتراضية الكاملة: `operator.admin`، و`operator.approvals`، و`operator.pairing`، و`operator.read`، و`operator.talk.secrets`، و`operator.write`. ويعامل دورات الدردشة على أنها دورات مرسلة من المالك. | | HTTP موثوق يحمل الهوية (مصادقة الوكيل الموثوق، أو `gateway.auth.mode="none"` على دخول خاص) | يحترم `x-openclaw-scopes` عند وجودها؛ ويعود إلى مجموعة نطاقات المشغّل الافتراضية عند غيابها. ولا يفقد دلالات المالك إلا عندما يضيّق المستدعي النطاقات صراحةً ويحذف `operator.admin`. ويتطلب `operator.admin` لعناصر التحكم على مستوى المالك مثل `x-openclaw-model`. | راجع [نطاقات المشغّل](/ar/gateway/operator-scopes)، و[الأمان](/ar/gateway/security)، و[الوصول عن بُعد](/ar/gateway/remote). ## المصادقة تستخدم إعدادات مصادقة Gateway (راجع [مصادقة الوكيل الموثوق](/ar/gateway/trusted-proxy-auth) للاطلاع على تفاصيل هذا الوضع): | الوضع | كيفية المصادقة | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gateway.auth.mode="token"` | `Authorization: Bearer `. يُضبط عبر `gateway.auth.token` أو `OPENCLAW_GATEWAY_TOKEN`. | | `gateway.auth.mode="password"` | `Authorization: Bearer `. يُضبط عبر `gateway.auth.password` أو `OPENCLAW_GATEWAY_PASSWORD`. | | `gateway.auth.mode="trusted-proxy"` | وجّه الاتصال عبر الوكيل المدرِك للهوية الذي تم إعداده؛ إذ يحقن ترويسات الهوية المطلوبة. تحتاج وكلاء local loopback على المضيف نفسه إلى ضبط `gateway.auth.trustedProxy.allowLoopback = true` صراحةً. | | `gateway.auth.mode="none"` | لا يلزم وجود ترويسة مصادقة (للدخول الخاص فقط). | ملاحظات: - يمكن للمستدعين على المضيف نفسه الذين يتجاوزون الوكيل في Gateway يعمل بوضع `trusted-proxy` الرجوع مباشرةً إلى `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`. ويؤدي وجود أي دليل في ترويسات `Forwarded` أو `X-Forwarded-*` أو `X-Real-IP` إلى إبقاء الطلب على مسار الوكيل الموثوق بدلًا من ذلك. - إذا تم إعداد `gateway.auth.rateLimit` وفشلت محاولات مصادقة كثيرة جدًا، فستعيد نقطة النهاية الرمز `429` مع ترويسة `Retry-After`. ## متى تستخدم نقطة النهاية هذه - فضّلها على إضافة قناة مضمّنة جديدة عندما لا يكون تكاملك سوى واجهة مشغّل/عميل أخرى لـ Gateway نفسه. - بالنسبة إلى عملاء الأجهزة المحمولة الأصليين الذين يتصلون مباشرةً بـ Gateway بعيد، فضّل [WebChat](/ar/web/webchat) أو [بروتوكول Gateway](/ar/gateway/protocol) مع تدفق التهيئة الأولية للجهاز المقترن/رمز الجهاز المميز، لكي لا يحتاج الجهاز إلى رمز HTTP مميز/كلمة مرور مشتركة. - أنشئ Plugin قناة بدلًا من ذلك عند التكامل مع شبكة مراسلة خارجية لها مستخدموها أو غرفها أو تسليم Webhook أو نقلها الصادر. راجع [إنشاء Plugins](/ar/plugins/building-plugins). ## عقد النموذج القائم على الوكيل أولًا يتعامل OpenClaw مع حقل OpenAI المسمى `model` باعتباره **هدف وكيل**، وليس معرّف نموذج خامًا لمزوّد. | قيمة `model` | التوجيه إلى | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `openclaw` | الوكيل الافتراضي المُعدّ | | `openclaw/default` | الوكيل الافتراضي المُعدّ (اسم مستعار ثابت؛ يمكن تضمينه في الشفرة بأمان حتى إذا تغيّر معرّف الوكيل الافتراضي الحقيقي بين البيئات) | | `openclaw/` أو `openclaw:` | وكيل محدد | | `agent:` | وكيل محدد (اسم مستعار للتوافق) | ترويسات الطلب الاختيارية: | الترويسة | التأثير | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-openclaw-model: ` | تتجاوز نموذج الواجهة الخلفية للوكيل المحدد. يمكن للمستدعين الحاملين لسر مشترك استخدام ذلك مباشرةً؛ أما المستدعون الحاملون للهوية (الوكيل الموثوق، أو الدخول الخاص بلا مصادقة مع `x-openclaw-scopes`) فيحتاجون إلى `operator.admin`، وإلا فستكون النتيجة `403 missing scope: operator.admin`. | | `x-openclaw-agent-id: ` | تجاوز للتوافق عند اختيار الوكيل. | | `x-openclaw-session-key: ` | توجيه صريح للجلسة. يُرفض بالخطأ `400 invalid_request_error` إذا استخدم مساحة أسماء داخلية محجوزة (`subagent:`، أو `cron:`، أو `acp:`). | | `x-openclaw-message-channel: ` | يضبط سياق قناة الدخول الاصطناعية للمطالبات/السياسات المدركة للقناة. | يسرد `/v1/models` أهداف الوكلاء ذات المستوى الأعلى (`openclaw`، و`openclaw/default`، و`openclaw/`)، وليس نماذج مزوّدي الواجهة الخلفية ولا الوكلاء الفرعيين؛ إذ يظل الوكلاء الفرعيون جزءًا من بنية التنفيذ الداخلية. وإذا حذفت `x-openclaw-model`، فسيعمل الوكيل المحدد باستخدام نموذجه المعتاد المُعدّ. يستخدم `/v1/embeddings` معرّفات `model` نفسها الخاصة بأهداف الوكلاء. أرسل `x-openclaw-model` (من مستدعٍ يستخدم سرًا مشتركًا، أو مستدعٍ يحمل الهوية ولديه `operator.admin`) لاختيار نموذج تضمين محدد؛ وإلا فسيستخدم الطلب إعداد التضمين المعتاد للوكيل المحدد. ## سلوك الجلسة تكون نقطة النهاية افتراضيًا **عديمة الحالة لكل طلب** (يتم إنشاء مفتاح جلسة جديد في كل استدعاء). إذا تضمّن الطلب سلسلة OpenAI باسم `user`، فسيشتق Gateway منها مفتاح جلسة ثابتًا لكي تتمكن الاستدعاءات المتكررة من مشاركة جلسة وكيل. بالنسبة إلى التطبيقات المخصصة، أعد استخدام قيمة `user` نفسها لكل سلسلة محادثة؛ وتجنّب المعرّفات على مستوى الحساب إلا إذا أردت أن تشارك عدة محادثات/أجهزة جلسة OpenClaw واحدة. استخدم `x-openclaw-session-key` فقط عندما تحتاج إلى تحكم صريح في التوجيه عبر عدة عملاء/سلاسل، باستخدام مفاتيح يملكها التطبيق وتتجنب مساحات الأسماء المحجوزة أعلاه. ## حدود الطلبات (الإعدادات) يمكن ضبط القيم الافتراضية ضمن `gateway.http.endpoints.chatCompletions`: ```json5 { 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, }, }, }, }, }, } ``` القيم الافتراضية عند الحذف: | المفتاح | القيمة الافتراضية | | --------------------- | ------------------------------------------------------------------------------------------------- | | `maxBodyBytes` | 20MB | | `maxImageParts` | 8 (الحد الأقصى لأجزاء `image_url` المقروءة من أحدث رسالة للمستخدم) | | `maxTotalImageBytes` | 20MB (إجمالي وحدات البايت المفكوك ترميزها عبر جميع أجزاء `image_url` في طلب واحد) | | `images.allowUrl` | `false` (تُرفض أجزاء `image_url` الآتية من عنوان URL ما لم تُفعّل) | | `images.maxBytes` | 10MB لكل صورة | | `images.maxRedirects` | 3 | | `images.timeoutMs` | 10s | تُقبل مصادر `image_url` بتنسيقي HEIC/HEIF وتُطبّع إلى JPEG قبل تسليمها إلى المزوّد عبر معالج الصور المشترك في OpenClaw ‏(Rastermill)، والذي يرجع إلى محوّل نظام (`sips` أو ImageMagick أو GraphicsMagick أو ffmpeg) للتنسيقات التي تحتاج إلى دعم برنامج ترميز خارجي. ملاحظة أمنية: لا يؤدي إدراج اسم مضيف في قائمة السماح إلى تجاوز حظر عناوين IP الخاصة/الداخلية. بالنسبة إلى بوابات Gateway المكشوفة للإنترنت، طبّق ضوابط خروج الشبكة بالإضافة إلى وسائل الحماية على مستوى التطبيق. راجع [الأمان](/ar/gateway/security). ## عقد أداة المحادثة يدعم `/v1/chat/completions` مجموعة فرعية من أدوات الدوال متوافقة مع عملاء محادثة OpenAI الشائعين. ### حقول الطلب المدعومة | الحقل | ملاحظات | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `tools` | مصفوفة من `{ "type": "function", "function": { ... } }` | | `tool_choice` | `"auto"` أو `"none"` أو `"required"` أو `{ "type": "function", "function": { "name": "..." } }` | | `messages[*].role: "tool"` | المنعطفات اللاحقة | | `messages[*].tool_call_id` | يربط نتيجة أداة باستدعاء أداة سابق | | `max_completion_tokens` | رقم؛ الحد الأقصى لكل استدعاء لإجمالي رموز الإكمال (بما فيها رموز الاستدلال). اسم الحقل الحالي؛ يُستخدم عند إرساله مع `max_tokens`. | | `max_tokens` | رقم؛ اسم بديل قديم، ويُتجاهل عند وجود `max_completion_tokens` أيضًا. | | `temperature` | رقم من 0 إلى 2؛ يُمرَّر إلى المزوّد المنبع وفق أفضل جهد ممكن. يُعاد `400 invalid_request_error` إذا كان خارج النطاق. | | `top_p` | رقم من 0 إلى 1؛ وفق أفضل جهد ممكن. يُعاد `400 invalid_request_error` إذا كان خارج النطاق. | | `frequency_penalty` | رقم من ‎-2.0 إلى 2.0؛ وفق أفضل جهد ممكن. يُعاد `400 invalid_request_error` إذا كان خارج النطاق. | | `presence_penalty` | رقم من ‎-2.0 إلى 2.0؛ وفق أفضل جهد ممكن. يُعاد `400 invalid_request_error` إذا كان خارج النطاق. | | `seed` | عدد صحيح؛ وفق أفضل جهد ممكن. يُعاد `400 invalid_request_error` للقيم غير الصحيحة. | | `stop` | سلسلة أو مصفوفة تضم حتى 4 سلاسل؛ وفق أفضل جهد ممكن. يُعاد `400 invalid_request_error` عند وجود أكثر من 4 تسلسلات أو إدخالات غير نصية/فارغة. | تمر جميع حقول أخذ العينات وحدود الرموز عبر قناة معاملات تدفق الوكيل نفسها، وتُمرَّر وفق أفضل جهد ممكن: - حد الرموز: يختار نقل المزوّد اسم الحقل على السلك: `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: ` - ينتهي التدفق بالسطر `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`). اختبار تحقق سريع: ```bash curl -sS http://127.0.0.1:18789/v1/models \ -H 'Authorization: Bearer YOUR_TOKEN' ``` إذا أعاد ذلك `openclaw/default`، فيمكن لمعظم إعدادات Open WebUI الاتصال باستخدام عنوان URL الأساسي والرمز نفسيهما. ## أمثلة جلسة ثابتة لمحادثة واحدة في تطبيق: ```bash 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` نفسها في الاستدعاءات اللاحقة لتلك المحادثة لمواصلة جلسة الوكيل نفسها. دون بث: ```bash 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"}] }' ``` مع البث: ```bash 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"}] }' ``` سرد النماذج: ```bash curl -sS http://127.0.0.1:18789/v1/models \ -H 'Authorization: Bearer YOUR_TOKEN' ``` جلب نموذج واحد: ```bash curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \ -H 'Authorization: Bearer YOUR_TOKEN' ``` إنشاء تضمينات: ```bash 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` كسلسلة أو مصفوفة سلاسل. ## ذو صلة - [مرجع الإعدادات](/ar/gateway/configuration-reference) - [نطاقات المشغّل](/ar/gateway/operator-scopes) - [OpenAI](/ar/providers/openai)