vLLM - OpenClaw

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

الخاصية	القيمة
معرّف المزوّد	`vllm`
API	`openai-completions` (متوافق مع OpenAI)
المصادقة	متغير البيئة `VLLM_API_KEY`
عنوان URL الأساسي الافتراضي	`http://127.0.0.1:8000/v1`

البدء

Start vLLM with an OpenAI-compatible server

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

http://127.0.0.1:8000/v1

Set the API key environment variable

أي قيمة تعمل إذا كان خادمك لا يفرض المصادقة:

export VLLM_API_KEY="vllm-local"

Select a model

استبدلها بأحد معرّفات نماذج vLLM لديك:

{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}

Verify the model is available

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",
        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/*": {},
      },
    },
  },
}

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

Proxy-style behavior

يُعامل vLLM كواجهة خلفية /v1 متوافقة مع OpenAI بنمط الوكيل، وليس كنقطة نهاية OpenAI أصلية. يعني ذلك:

السلوك	مُطبّق؟
تشكيل طلبات OpenAI الأصلية	لا
`service_tier`	لا يُرسل
`store` في Responses	لا يُرسل
تلميحات ذاكرة التخزين المؤقت للموجه	لا تُرسل
تشكيل حمولة توافق الاستدلال مع OpenAI	غير مُطبّق
رؤوس إسناد OpenClaw المخفية	لا تُحقن على عناوين URL الأساسية المخصصة

Qwen thinking controls

بالنسبة إلى نماذج Qwen المقدّمة عبر vLLM، اضبط compat.thinkingFormat: "qwen-chat-template" على صف نموذج المزوّد المضبوط عندما يتوقع الخادم معاملات Qwen chat-template kwargs. تعرض النماذج المضبوطة بهذه الطريقة ملف تعريف /think ثنائيًا (off، on) لأن تفكير قالب Qwen هو علم طلب تشغيل/إيقاف، وليس سلّم جهد بنمط OpenAI.

{
  models: {
    providers: {
      vllm: {
        models: [
          {
            id: "Qwen/Qwen3-8B",
            name: "Qwen3 8B",
            reasoning: true,
            compat: { thinkingFormat: "qwen-chat-template" },
          },
        ],
      },
    },
  },
}

يربط OpenClaw الأمر /think off بما يلي:

{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "preserve_thinking": true
  }
}

ترسل مستويات التفكير غير off القيمة enable_thinking: true. إذا كانت نقطة النهاية لديك تتوقع بدلًا من ذلك أعلامًا علوية بنمط DashScope، فاستخدم compat.thinkingFormat: "qwen" لإرسال enable_thinking في جذر الطلب.

Nemotron 3 thinking controls

يمكن لـ vLLM/Nemotron 3 استخدام chat-template 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,
            },
          },
        },
      },
    },
  },
}

Qwen tool calls appear as text

تأكد أولًا من أن 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، ولا تستخدم وكيلًا يحوّل نص المساعد الاعتباطي عشوائيًا إلى استدعاءات أدوات قابلة للتنفيذ.

Custom base URL

إذا كان خادم vLLM لديك يعمل على مضيف أو منفذ غير افتراضي، فاضبط baseUrl في ضبط المزوّد الصريح:

{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:9000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-custom-model",
            name: "Remote vLLM Model",
            reasoning: false,
            input: ["text"],
            contextWindow: 64000,
            maxTokens: 4096,
          },
        ],
      },
    },
  },
}

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

Slow first response or remote server timeout

بالنسبة إلى النماذج المحلية الكبيرة، أو مضيفي LAN البعيدين، أو روابط tailnet، اضبط مهلة طلب على نطاق المزوّد:

{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [{ id: "your-model-id", name: "Local vLLM Model" }],
      },
    },
  },
}

ينطبق timeoutSeconds على طلبات HTTP لنماذج vLLM فقط، بما في ذلك إعداد الاتصال، ورؤوس الاستجابة، وبث الجسم، والإجهاض الإجمالي للجلب المحمي. فضّل هذا قبل زيادة agents.defaults.timeoutSeconds، الذي يتحكم في تشغيل الوكيل بالكامل.

Server not reachable

تحقق من أن خادم vLLM يعمل ويمكن الوصول إليه:

curl http://127.0.0.1:8000/v1/models

إذا رأيت خطأ اتصال، فتحقق من المضيف والمنفذ وأن vLLM بدأ بوضع الخادم المتوافق مع OpenAI. بالنسبة إلى نقاط نهاية loopback أو LAN أو Tailscale الصريحة، يثق OpenClaw في أصل models.providers.vllm.baseUrl المضبوط بدقة لطلبات النماذج المحمية. تبقى أصول metadata/link-local محظورة دون تفعيل صريح. اضبط models.providers.vllm.request.allowPrivateNetwork: true فقط عندما يجب أن تصل طلبات vLLM إلى أصل خاص آخر، واضبطه على false لإلغاء الثقة بالأصل الدقيق.

Auth errors on requests

إذا فشلت الطلبات بسبب أخطاء مصادقة، فاضبط VLLM_API_KEY حقيقيًا يطابق ضبط خادمك، أو اضبط المزوّد صراحةً ضمن models.providers.vllm.

إذا كان خادم vLLM لديك لا يفرض المصادقة، فإن أي قيمة غير فارغة لـ VLLM_API_KEY تعمل كإشارة تفعيل لـ OpenClaw.

No models discovered

يتطلب الاكتشاف التلقائي ضبط VLLM_API_KEY. إذا عرّفت models.providers.vllm، يستخدم OpenClaw نماذجك المعلنة فقط ما لم يتضمن agents.defaults.models القيمة "vllm/*": {}.

Tools render as raw text

إذا طبع نموذج Qwen صياغة أدوات JSON/XML بدلًا من تنفيذ Skill، فراجع إرشادات Qwen في الضبط المتقدم أعلاه. الإصلاح المعتاد هو:

بدء vLLM بالمحلل/القالب الصحيح لذلك النموذج
تأكيد معرّف النموذج الدقيق باستخدام openclaw models list --provider vllm
إضافة تجاوز مخصص لكل نموذج لـ params.extra_body.tool_choice: "required" فقط إذا كان tool_choice: "auto" لا يزال يعيد استدعاءات أدوات فارغة أو نصية فقط

مزيد من المساعدة: استكشاف الأخطاء وإصلاحها والأسئلة الشائعة.

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

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

OpenAI

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

OAuth والمصادقة

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

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

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

​البدء

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

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

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

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

​ذات صلة

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

OpenAI

OAuth والمصادقة

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

البدء

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

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

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

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

ذات صلة