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:

http://127.0.0.1:8000/v1

Atur variabel lingkungan kunci API

Nilai apa pun berfungsi jika server Anda tidak memberlakukan autentikasi:

export VLLM_API_KEY="vllm-local"

Pilih model

Ganti dengan salah satu ID model vLLM Anda:

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

Verifikasi bahwa model tersedia

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:

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

dan mengonversi ID yang dikembalikan menjadi entri model.

Jika Anda mengatur models.providers.vllm secara eksplisit, OpenClaw menggunakan model yang Anda deklarasikan secara default. Tambahkan "vllm/*": {} ke agents.defaults.models saat Anda ingin OpenClaw mengueri endpoint /models penyedia yang dikonfigurasi tersebut dan menyertakan semua model vLLM yang diiklankan.

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

{
  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:

{
  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:

{
  "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:

{
  "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.

{
  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:

{
  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:

openclaw models list --provider vllm

Anda dapat menerapkan override yang sama dari CLI:

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:

{
  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:

{
  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:

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.

Jika server vLLM Anda tidak memberlakukan autentikasi, nilai tidak kosong apa pun untuk VLLM_API_KEY berfungsi sebagai sinyal opt-in untuk OpenClaw.

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

Bantuan lebih lanjut: Pemecahan masalah dan FAQ.

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.

Overview

Concepts and configuration

Providers

Memulai

Penemuan model (penyedia implisit)

Konfigurasi eksplisit (model manual)

Konfigurasi lanjutan

Pemecahan masalah

Terkait

Pemilihan model

OpenAI

OAuth dan autentikasi

Pemecahan masalah

Overview

Concepts and configuration

Providers

Documentation Index

​Memulai

​Penemuan model (penyedia implisit)

​Konfigurasi eksplisit (model manual)

​Konfigurasi lanjutan

​Pemecahan masalah

​Terkait

Pemilihan model

OpenAI

OAuth dan autentikasi

Pemecahan masalah

Memulai

Penemuan model (penyedia implisit)

Konfigurasi eksplisit (model manual)

Konfigurasi lanjutan

Pemecahan masalah

Terkait