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

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.

يمكن لـ vLLM تقديم نماذج مفتوحة المصدر (وبعض النماذج المخصصة) عبر واجهة HTTP API متوافقة مع OpenAI. يتصل OpenClaw بـ vLLM باستخدام واجهة API openai-completions. يمكن لـ OpenClaw أيضًا الاكتشاف التلقائي للنماذج المتاحة من vLLM عند تفعيل ذلك باستخدام VLLM_API_KEY (تعمل أي قيمة إذا كان خادمك لا يفرض المصادقة). استخدم vllm/* في agents.defaults.models لإبقاء الاكتشاف ديناميكيًا عندما تضبط أيضًا عنوان URL أساسيًا مخصصًا لـ vLLM. يتعامل OpenClaw مع vllm كمزوّد محلي متوافق مع OpenAI يدعم محاسبة الاستخدام المتدفقة، لذلك يمكن تحديث أعداد رموز الحالة/السياق من استجابات stream_options.include_usage.
الخاصيةالقيمة
معرّف المزوّدvllm
APIopenai-completions (متوافقة مع OpenAI)
المصادقةمتغير البيئة VLLM_API_KEY
عنوان URL الأساسي الافتراضيhttp://127.0.0.1:8000/v1

​
البدء

1

ابدأ vLLM بخادم متوافق مع OpenAI

يجب أن يكشف عنوان URL الأساسي لديك نقاط نهاية /v1 (مثل /v1/models و/v1/chat/completions). يعمل vLLM عادةً على:
http://127.0.0.1:8000/v1
2

اضبط متغير البيئة الخاص بمفتاح API

تعمل أي قيمة إذا كان خادمك لا يفرض المصادقة:
export VLLM_API_KEY="vllm-local"
3

اختر نموذجًا

استبدله بأحد معرّفات نماذج vLLM لديك:
{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}
4

تحقق من توفر النموذج

openclaw models list --provider vllm

​
اكتشاف النماذج (مزوّد ضمني)

عند ضبط VLLM_API_KEY (أو وجود ملف تعريف مصادقة) وعدم تعريف models.providers.vllm، يستعلم OpenClaw عن: 
GET http://127.0.0.1:8000/v1/models
ويحوّل المعرّفات المرتجعة إلى إدخالات نماذج.
إذا ضبطت models.providers.vllm صراحةً، يستخدم OpenClaw النماذج التي صرّحت بها افتراضيًا. أضف "vllm/*": {} إلى agents.defaults.models عندما تريد أن يستعلم OpenClaw عن نقطة نهاية /models لذلك المزوّد المضبوط وأن يضمّن كل نماذج vLLM المعلنة.

​
الضبط الصريح (النماذج اليدوية)

استخدم الضبط الصريح عندما:
  • يعمل vLLM على مضيف أو منفذ مختلف
  • تريد تثبيت قيم contextWindow أو maxTokens
  • يتطلب خادمك مفتاح API حقيقيًا (أو تريد التحكم في الرؤوس)
  • تتصل بنقطة نهاية vLLM موثوقة عبر loopback أو LAN أو Tailscale
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        request: { allowPrivateNetwork: true },
        timeoutSeconds: 300, // Optional: extend connect/header/body/request timeout for slow local models
        models: [
          {
            id: "your-model-id",
            name: "Local vLLM Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
لإبقاء هذا المزوّد ديناميكيًا دون إدراج كل نموذج يدويًا، أضف حرف بدل للمزوّد إلى كتالوج النماذج المرئي: 
{
  agents: {
    defaults: {
      models: {
        "vllm/*": {},
      },
    },
  },
}

​
الضبط المتقدم

يُعامَل vLLM كواجهة خلفية /v1 متوافقة مع OpenAI بنمط الوكيل، وليس كنقطة نهاية OpenAI أصلية. يعني هذا:
السلوكمطبّق؟
تشكيل طلب OpenAI الأصليلا
service_tierلا يُرسل
Responses storeلا يُرسل
تلميحات ذاكرة التخزين المؤقت للمطالباتلا تُرسل
تشكيل حمولة توافق الاستدلال في OpenAIغير مطبّق
رؤوس إسناد OpenClaw المخفيةلا تُحقن في عناوين URL الأساسية المخصصة
لنماذج Qwen المقدمة عبر vLLM، اضبط params.qwenThinkingFormat: "chat-template" على إدخال النموذج عندما يتوقع الخادم kwargs لقالب محادثة Qwen. يربط OpenClaw الأمر /think off بـ:
{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "preserve_thinking": true
  }
}
ترسل مستويات التفكير غير off القيمة enable_thinking: true. إذا كانت نقطة النهاية لديك تتوقع بدلًا من ذلك أعلامًا علوية بنمط DashScope، فاستخدم params.qwenThinkingFormat: "top-level" لإرسال enable_thinking في جذر الطلب. يُقبل أيضًا params.qwen_thinking_format بصيغة snake-case.
يمكن لـ vLLM/Nemotron 3 استخدام kwargs لقالب المحادثة للتحكم فيما إذا كان الاستدلال يُعاد كاستدلال مخفي أو كنص إجابة مرئي. عندما تستخدم جلسة OpenClaw vllm/nemotron-3-* مع إيقاف التفكير، يرسل Plugin vLLM المضمّن:
{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "force_nonempty_content": true
  }
}
لتخصيص هذه القيم، اضبط chat_template_kwargs ضمن معاملات النموذج. إذا ضبطت أيضًا params.extra_body.chat_template_kwargs، فستكون لتلك القيمة الأسبقية النهائية لأن extra_body هو آخر تجاوز لجسم الطلب.
{
  agents: {
    defaults: {
      models: {
        "vllm/nemotron-3-super": {
          params: {
            chat_template_kwargs: {
              enable_thinking: false,
              force_nonempty_content: true,
            },
          },
        },
      },
    },
  },
}
تأكد أولًا من بدء vLLM باستخدام محلل استدعاءات الأدوات وقالب المحادثة المناسبين للنموذج. على سبيل المثال، توثق vLLM استخدام hermes لنماذج Qwen2.5 وqwen3_xml لنماذج Qwen3-Coder.الأعراض:
  • لا تعمل skills أو الأدوات مطلقًا
  • يطبع المساعد JSON/XML خامًا مثل {"name":"read","arguments":...}
  • يعيد vLLM مصفوفة tool_calls فارغة عندما يرسل OpenClaw tool_choice: "auto"
تُعيد بعض مجموعات Qwen/vLLM استدعاءات أدوات منظمة فقط عندما يستخدم الطلب tool_choice: "required". لتلك إدخالات النماذج، افرض حقل الطلب المتوافق مع OpenAI باستخدام params.extra_body:
{
  agents: {
    defaults: {
      models: {
        "vllm/Qwen-Qwen2.5-Coder-32B-Instruct": {
          params: {
            extra_body: {
              tool_choice: "required",
            },
          },
        },
      },
    },
  },
}
استبدل Qwen-Qwen2.5-Coder-32B-Instruct بالمعرّف الدقيق الذي يعيده:
openclaw models list --provider vllm
يمكنك تطبيق التجاوز نفسه من CLI:
openclaw config set agents.defaults.models '{"vllm/Qwen-Qwen2.5-Coder-32B-Instruct":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
هذا حل توافق اختياري. يجعل كل دورة نموذج مع الأدوات تتطلب استدعاء أداة، لذلك استخدمه فقط لإدخال نموذج محلي مخصص يكون فيه هذا السلوك مقبولًا. لا تستخدمه كافتراضي عام لكل نماذج vLLM، ولا تستخدم وكيلًا يحوّل عشوائيًا أي نص مساعد إلى استدعاءات أدوات قابلة للتنفيذ.
إذا كان خادم vLLM يعمل على مضيف أو منفذ غير افتراضي، فاضبط baseUrl في ضبط المزوّد الصريح:
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:9000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        request: { allowPrivateNetwork: true },
        timeoutSeconds: 300,
        models: [
          {
            id: "my-custom-model",
            name: "Remote vLLM Model",
            reasoning: false,
            input: ["text"],
            contextWindow: 64000,
            maxTokens: 4096,
          },
        ],
      },
    },
  },
}

​
استكشاف الأخطاء وإصلاحها

للنماذج المحلية الكبيرة، أو مضيفي LAN البعيدين، أو روابط tailnet، اضبط مهلة طلب على مستوى المزوّد:
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        request: { allowPrivateNetwork: true },
        timeoutSeconds: 300,
        models: [{ id: "your-model-id", name: "Local vLLM Model" }],
      },
    },
  },
}
ينطبق timeoutSeconds على طلبات HTTP لنماذج vLLM فقط، بما في ذلك إعداد الاتصال، ورؤوس الاستجابة، وتدفق الجسم، وإحباط guarded-fetch الإجمالي. فضّل هذا قبل زيادة agents.defaults.timeoutSeconds، الذي يتحكم في تشغيل الوكيل بالكامل.
تحقق من أن خادم vLLM يعمل ويمكن الوصول إليه:
curl http://127.0.0.1:8000/v1/models
إذا رأيت خطأ اتصال، فتحقق من المضيف والمنفذ وأن vLLM بدأ بوضع الخادم المتوافق مع OpenAI. ولنقاط نهاية loopback أو LAN أو Tailscale الصريحة، اضبط أيضًا models.providers.vllm.request.allowPrivateNetwork: true؛ تحظر طلبات المزوّد عناوين URL للشبكات الخاصة افتراضيًا ما لم يكن المزوّد موثوقًا به صراحةً.
إذا فشلت الطلبات بسبب أخطاء المصادقة، فاضبط VLLM_API_KEY حقيقيًا يطابق ضبط الخادم لديك، أو اضبط المزوّد صراحةً ضمن models.providers.vllm.
إذا كان خادم vLLM لديك لا يفرض المصادقة، تعمل أي قيمة غير فارغة لـ VLLM_API_KEY كإشارة تفعيل اختيارية لـ OpenClaw.
يتطلب الاكتشاف التلقائي ضبط VLLM_API_KEY. إذا عرّفت models.providers.vllm، يستخدم OpenClaw النماذج التي صرّحت بها فقط ما لم يتضمن agents.defaults.models القيمة "vllm/*": {}.
إذا طبع نموذج Qwen صيغة أدوات JSON/XML بدلًا من تنفيذ skill، فتحقق من إرشادات Qwen في الضبط المتقدم أعلاه. الإصلاح المعتاد هو:
  • بدء vLLM بالمحلل/القالب الصحيح لذلك النموذج
  • تأكيد معرّف النموذج الدقيق باستخدام openclaw models list --provider vllm
  • إضافة تجاوز مخصص لكل نموذج لـ params.extra_body.tool_choice: "required" فقط إذا ظل tool_choice: "auto" يعيد استدعاءات أدوات فارغة أو نصية فقط
مزيد من المساعدة: استكشاف الأخطاء وإصلاحها والأسئلة الشائعة.

​
ذو صلة

اختيار النموذج

اختيار المزوّدين، ومراجع النماذج، وسلوك تجاوز الفشل.

OpenAI

مزوّد OpenAI الأصلي وسلوك المسار المتوافق مع OpenAI.

OAuth والمصادقة

تفاصيل المصادقة وقواعد إعادة استخدام بيانات الاعتماد.

استكشاف الأخطاء وإصلاحها

المشكلات الشائعة وكيفية حلها.