Providers

vLLM

vLLM dapat menyajikan model open-source (dan beberapa model kustom) melalui API HTTP yang kompatibel dengan OpenAI. OpenClaw terhubung ke vLLM menggunakan API openai-completions.

OpenClaw juga dapat menemukan secara otomatis model yang tersedia dari vLLM saat Anda ikut serta dengan VLLM_API_KEY (nilai apa pun berfungsi jika server Anda tidak memberlakukan autentikasi). Gunakan vllm/* di agents.defaults.models agar penemuan tetap dinamis saat Anda juga mengonfigurasi URL dasar vLLM kustom.

OpenClaw memperlakukan vllm sebagai penyedia lokal yang kompatibel dengan OpenAI yang mendukung akuntansi penggunaan streaming, sehingga jumlah token status/konteks dapat diperbarui dari respons stream_options.include_usage.

Properti	Nilai
ID Penyedia	`vllm`
API	`openai-completions` (kompatibel dengan OpenAI)
Autentikasi	variabel lingkungan `VLLM_API_KEY`
URL dasar default	`http://127.0.0.1:8000/v1`

Memulai

Mulai vLLM dengan server yang kompatibel dengan OpenAI

URL dasar Anda harus mengekspos endpoint /v1 (mis. /v1/models, /v1/chat/completions). vLLM umumnya berjalan di:

Code

http://127.0.0.1:8000/v1

Atur variabel lingkungan kunci API

Nilai apa pun berfungsi jika server Anda tidak memberlakukan autentikasi:

bash

export VLLM_API_KEY="vllm-local"

Pilih model

Ganti dengan salah satu ID model vLLM Anda:

json5

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

Verifikasi bahwa model tersedia

bash

openclaw models list --provider vllm

Penemuan model (penyedia implisit)

Saat VLLM_API_KEY diatur (atau profil autentikasi ada) dan Anda tidak mendefinisikan models.providers.vllm, OpenClaw melakukan kueri:

Code

GET http://127.0.0.1:8000/v1/models

dan mengonversi ID yang dikembalikan menjadi entri model.

Konfigurasi eksplisit (model manual)

Gunakan konfigurasi eksplisit saat:

vLLM berjalan di host atau port yang berbeda
Anda ingin menetapkan nilai contextWindow atau maxTokens
Server Anda memerlukan kunci API nyata (atau Anda ingin mengontrol header)
Anda terhubung ke endpoint vLLM loopback, LAN, atau Tailscale tepercaya

json5

{  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,          },        ],      },    },  },}

Agar penyedia ini tetap dinamis tanpa mencantumkan setiap model secara manual, tambahkan wildcard penyedia ke katalog model yang terlihat:

json5

{  agents: {    defaults: {      models: {        "vllm/*": {},      },    },  },}

Konfigurasi lanjutan

Perilaku bergaya proxy

vLLM diperlakukan sebagai backend /v1 bergaya proxy yang kompatibel dengan OpenAI, bukan endpoint OpenAI native. Ini berarti:

Perilaku	Diterapkan?
Pembentukan permintaan OpenAI native	Tidak
`service_tier`	Tidak dikirim
`store` Responses	Tidak dikirim
Petunjuk cache prompt	Tidak dikirim
Pembentukan payload kompatibilitas reasoning OpenAI	Tidak diterapkan
Header atribusi OpenClaw tersembunyi	Tidak disisipkan pada URL dasar kustom

Kontrol thinking Qwen

Untuk model Qwen yang disajikan melalui vLLM, atur params.qwenThinkingFormat: "chat-template" pada entri model saat server mengharapkan kwargs chat-template Qwen. OpenClaw memetakan /think off ke:

json

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

Tingkat thinking non-off mengirim enable_thinking: true. Jika endpoint Anda mengharapkan flag tingkat atas bergaya DashScope, gunakan params.qwenThinkingFormat: "top-level" untuk mengirim enable_thinking pada root permintaan. Snake-case params.qwen_thinking_format juga diterima.

Kontrol thinking Nemotron 3

vLLM/Nemotron 3 dapat menggunakan kwargs chat-template untuk mengontrol apakah reasoning dikembalikan sebagai reasoning tersembunyi atau teks jawaban yang terlihat. Saat sesi OpenClaw menggunakan vllm/nemotron-3-* dengan thinking nonaktif, plugin vLLM bawaan mengirim:

json

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

Untuk menyesuaikan nilai ini, atur chat_template_kwargs di bawah params model. Jika Anda juga mengatur params.extra_body.chat_template_kwargs, nilai tersebut memiliki prioritas akhir karena extra_body adalah override isi permintaan terakhir.

json5

{  agents: {    defaults: {      models: {        "vllm/nemotron-3-super": {          params: {            chat_template_kwargs: {              enable_thinking: false,              force_nonempty_content: true,            },          },        },      },    },  },}

Panggilan tool Qwen muncul sebagai teks

Pertama, pastikan vLLM dimulai dengan parser tool-call dan template chat yang tepat untuk model tersebut. Misalnya, vLLM mendokumentasikan hermes untuk model Qwen2.5 dan qwen3_xml untuk model Qwen3-Coder.

Gejala:

skills atau tool tidak pernah berjalan
asisten mencetak JSON/XML mentah seperti {"name":"read","arguments":...}
vLLM mengembalikan array tool_calls kosong saat OpenClaw mengirim tool_choice: "auto"

Beberapa kombinasi Qwen/vLLM mengembalikan panggilan tool terstruktur hanya saat permintaan menggunakan tool_choice: "required". Untuk entri model tersebut, paksa field permintaan yang kompatibel dengan OpenAI dengan params.extra_body:

json5

{  agents: {    defaults: {      models: {        "vllm/Qwen-Qwen2.5-Coder-32B-Instruct": {          params: {            extra_body: {              tool_choice: "required",            },          },        },      },    },  },}

Ganti Qwen-Qwen2.5-Coder-32B-Instruct dengan id persis yang dikembalikan oleh:

bash

openclaw models list --provider vllm

Anda dapat menerapkan override yang sama dari CLI:

bash

openclaw config set agents.defaults.models '{"vllm/Qwen-Qwen2.5-Coder-32B-Instruct":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge

Ini adalah solusi kompatibilitas opt-in. Ini membuat setiap giliran model dengan tool mewajibkan panggilan tool, jadi gunakan hanya untuk entri model lokal khusus tempat perilaku tersebut dapat diterima. Jangan gunakan sebagai default global untuk semua model vLLM, dan jangan gunakan proxy yang secara membabi buta mengonversi teks asisten arbitrer menjadi panggilan tool yang dapat dieksekusi.

URL dasar kustom

Jika server vLLM Anda berjalan di host atau port non-default, atur baseUrl di konfigurasi penyedia eksplisit:

json5

{  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,          },        ],      },    },  },}

Pemecahan masalah

Respons pertama lambat atau server jarak jauh timeout

Untuk model lokal besar, host LAN jarak jauh, atau tautan tailnet, atur timeout permintaan cakupan penyedia:

json5

{  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 hanya berlaku untuk permintaan HTTP model vLLM, termasuk penyiapan koneksi, header respons, streaming isi, dan total pembatalan guarded-fetch. Utamakan ini sebelum menaikkan agents.defaults.timeoutSeconds, yang mengontrol seluruh proses agen.

Server tidak dapat dijangkau

Periksa bahwa server vLLM berjalan dan dapat diakses:

bash

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

Jika Anda melihat kesalahan koneksi, verifikasi host, port, dan bahwa vLLM dimulai dengan mode server yang kompatibel dengan OpenAI. Untuk endpoint loopback, LAN, atau Tailscale eksplisit, atur juga models.providers.vllm.request.allowPrivateNetwork: true; permintaan penyedia memblokir URL jaringan privat secara default kecuali penyedia dipercaya secara eksplisit.

Kesalahan autentikasi pada permintaan

Jika permintaan gagal dengan kesalahan autentikasi, atur VLLM_API_KEY nyata yang cocok dengan konfigurasi server Anda, atau konfigurasikan penyedia secara eksplisit di bawah models.providers.vllm.

Tidak ada model yang ditemukan

Penemuan otomatis memerlukan VLLM_API_KEY untuk diatur. Jika Anda telah mendefinisikan models.providers.vllm, OpenClaw hanya menggunakan model yang Anda deklarasikan kecuali agents.defaults.models menyertakan "vllm/*": {}.

Tool dirender sebagai teks mentah

Jika model Qwen mencetak sintaks tool JSON/XML alih-alih mengeksekusi skill, periksa panduan Qwen di Konfigurasi lanjutan di atas. Perbaikan biasanya adalah:

mulai vLLM dengan parser/template yang benar untuk model tersebut
konfirmasi id model persis dengan openclaw models list --provider vllm
tambahkan override khusus per model params.extra_body.tool_choice: "required" hanya jika tool_choice: "auto" masih mengembalikan panggilan tool kosong atau hanya teks

Terkait

Pemilihan model

Memilih penyedia, referensi model, dan perilaku failover.

OpenAI

Penyedia OpenAI native dan perilaku rute yang kompatibel dengan OpenAI.

OAuth dan autentikasi

Detail autentikasi dan aturan penggunaan ulang kredensial.

Pemecahan masalah

Masalah umum dan cara mengatasinya.

Was this useful?