إكمالات الدردشة في OpenAI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• POST /v1/chat/completions
• نفس منفذ Gateway (تعدد إرسال WS + HTTP): http://<gateway-host>:<port>/v1/chat/completions

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/responses

​

المصادقة

• مصادقة السر المشترك (gateway.auth.mode="token" أو "password"): Authorization: Bearer <token-or-password>
• مصادقة HTTP الموثوقة الحاملة للهوية (gateway.auth.mode="trusted-proxy"): وجّه عبر الوكيل المكوّن والواعي بالهوية ودعه يحقن ترويسات الهوية المطلوبة
• مصادقة مفتوحة لدخول خاص (gateway.auth.mode="none"): لا يلزم وجود ترويسة مصادقة

• عند gateway.auth.mode="token"، استخدم gateway.auth.token (أو OPENCLAW_GATEWAY_TOKEN).
• عند gateway.auth.mode="password"، استخدم gateway.auth.password (أو OPENCLAW_GATEWAY_PASSWORD).
• عند gateway.auth.mode="trusted-proxy"، يجب أن يأتي طلب HTTP من مصدر وكيل موثوق مكوّن؛ وتتطلب وكلاء local loopback على المضيف نفسه ضبطًا صريحًا لـ gateway.auth.trustedProxy.allowLoopback = true.
• إذا كان gateway.auth.rateLimit مكوّنًا وحدث عدد كبير جدًا من إخفاقات المصادقة، فترجع نقطة النهاية 429 مع Retry-After.

​

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

• مصادقة حامل HTTP هنا ليست نموذج نطاق ضيقًا لكل مستخدم.
• يجب التعامل مع رمز/كلمة مرور Gateway صالحة لنقطة النهاية هذه كبيانات اعتماد مالك/مشغّل.
• تمر الطلبات عبر مسار وكيل مستوى التحكم نفسه مثل إجراءات المشغّل الموثوقة.
• لا يوجد حد أدوات منفصل لغير المالك/لكل مستخدم على نقطة النهاية هذه؛ بمجرد أن يجتاز المستدعي مصادقة Gateway هنا، يعامل OpenClaw ذلك المستدعي كمشغّل موثوق لهذا Gateway.
• في أوضاع مصادقة السر المشترك (token وpassword)، تعيد نقطة النهاية الإعدادات الافتراضية العادية الكاملة للمشغّل حتى إذا أرسل المستدعي ترويسة x-openclaw-scopes أضيق.
• تحترم أوضاع HTTP الموثوقة الحاملة للهوية (مثل مصادقة الوكيل الموثوق أو gateway.auth.mode="none") ترويسة x-openclaw-scopes عند وجودها، وإلا فتعود إلى مجموعة نطاقات المشغّل الافتراضية العادية.
• إذا كانت سياسة الوكيل الهدف تسمح بأدوات حساسة، يمكن لنقطة النهاية هذه استخدامها.
• أبقِ نقطة النهاية هذه على loopback/tailnet/دخول خاص فقط؛ لا تعرضها مباشرة على الإنترنت العام.

• 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

​

عقد نموذج يعطي الأولوية للوكيل

• model: "openclaw" يوجّه إلى الوكيل الافتراضي المكوّن.
• model: "openclaw/default" يوجّه أيضًا إلى الوكيل الافتراضي المكوّن.
• model: "openclaw/<agentId>" يوجّه إلى وكيل محدد.

• x-openclaw-model: <provider/model-or-bare-id> يتجاوز نموذج الواجهة الخلفية للوكيل المحدد.
• x-openclaw-agent-id: <agentId> يبقى مدعومًا كتجاوز توافق.
• x-openclaw-session-key: <sessionKey> يتحكم بالكامل في توجيه الجلسة.
• x-openclaw-message-channel: <channel> يضبط سياق قناة الدخول الاصطناعية للمطالبات والسياسات الواعية بالقناة.

• model: "openclaw:<agentId>"
• model: "agent:<agentId>"

​

تفعيل نقطة النهاية

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

​

تعطيل نقطة النهاية

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

​

سلوك الجلسة

​

لماذا يهم هذا السطح

• تتوقع معظم إعدادات Open WebUI وLobeChat وLibreChat وجود /v1/models.
• تتوقع العديد من أنظمة RAG وجود /v1/embeddings.
• يمكن لعملاء محادثة OpenAI الحاليين عادةً البدء بـ /v1/chat/completions.
• يفضّل عملاء أكثر أصالة للوكيل بشكل متزايد /v1/responses.

​

قائمة النماذج وتوجيه الوكيل

​

البث (SSE)

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

​

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

​

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

• tools: مصفوفة من { "type": "function", "function": { ... } }
• tool_choice: "auto", "none"
• دورات متابعة messages[*].role: "tool"
• messages[*].tool_call_id لربط نتائج الأدوات باستدعاء أداة سابق
• max_completion_tokens: رقم؛ حد لكل استدعاء لإجمالي رموز الإكمال (بما في ذلك رموز الاستدلال). اسم حقل OpenAI Chat Completions الحالي؛ مفضّل عند إرسال كل من max_completion_tokens وmax_tokens.
• max_tokens: رقم؛ اسم مستعار قديم مقبول للتوافق الخلفي. يُتجاهل عند وجود max_completion_tokens أيضًا.

​

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

• tools ليست مصفوفة
• إدخالات أدوات ليست من نوع دالة
• tool.function.name مفقود
• متغيرات tool_choice مثل allowed_tools وcustom
• tool_choice: "required" (لا يُفرض بعد في وقت التشغيل؛ سيدعم بمجرد تنفيذ الفرض الصارم)
• tool_choice: { "type": "function", "function": { "name": "..." } } (نفس مبرر required)
• قيم tool_choice.function.name التي لا تطابق tools المقدمة

​

شكل استجابة الأدوات غير المبثوثة

• choices[0].finish_reason = "tool_calls"
• إدخالات choices[0].message.tool_calls[] مع:
  • id
  • type: "function"
  • function.name
  • function.arguments (سلسلة JSON)

​

شكل استجابة الأدوات المبثوثة

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

​

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

• رسالة استدعاء أداة المساعد السابقة
• رسالة واحدة أو أكثر من role: "tool" مع tool_call_id مطابق

​

إعداد سريع لـ 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 ‏openclaw/default كمعرّف نموذج المحادثة
• إذا أردت مزوّد/نموذج واجهة خلفية محددًا لذلك الوكيل، فاضبط النموذج الافتراضي العادي للوكيل أو أرسل x-openclaw-model

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

​

أمثلة

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/models أهداف وكلاء OpenClaw، وليس كتالوجات المزوّدين الخام.
• يكون openclaw/default موجودًا دائمًا، لذا يعمل معرّف ثابت واحد عبر البيئات.
• تنتمي تجاوزات المزوّد/النموذج في الواجهة الخلفية إلى x-openclaw-model، وليس إلى حقل model في OpenAI.
• يدعم /v1/embeddings استخدام input كسلسلة نصية أو مصفوفة من السلاسل النصية.

​

ذات صلة

• مرجع التكوين
• OpenAI