跳轉到主要內容
vLLM 透過 OpenAI 相容的 HTTP API 提供開放原始碼（以及部分自訂）模型。OpenClaw 使用 openai-completions API 連線，並可在你選擇使用 VLLM_API_KEY 時自動探索模型。
屬性值
提供者 IDvllm
APIopenai-completions（OpenAI 相容）
驗證VLLM_API_KEY 環境變數
預設基礎 URLhttp://127.0.0.1:8000/v1
串流用量支援（stream_options.include_usage）

​
開始使用

1

以 OpenAI 相容伺服器啟動 vLLM

你的基礎 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 模型 ID：
{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}
4

確認模型可用

openclaw models list --provider vllm
對於非互動式設定（CI、腳本），請直接傳入基礎 URL、金鑰和模型：
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice vllm \
  --custom-base-url "http://127.0.0.1:8000/v1" \
  --custom-api-key "vllm-local" \
  --custom-model-id "your-model-id"

​
模型探索（隱含提供者）

當已設定 VLLM_API_KEY（或存在驗證設定檔），且未定義 models.providers.vllm 時，OpenClaw 會查詢 GET http://127.0.0.1:8000/v1/models，並將傳回的 ID 轉換為模型項目。
如果你明確設定 models.providers.vllm，OpenClaw 只會使用你宣告的模型。將 "vllm/*": {} 新增至 agents.defaults.models，即可讓 OpenClaw 也查詢該已設定提供者的 /models 端點，並納入所有公告的 vLLM 模型。

​
明確設定

當 vLLM 執行在不同主機或連接埠、你想固定 contextWindow/maxTokens、你的伺服器需要真實 API 金鑰，或你要連線到受信任的 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 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 會被視為代理樣式的 OpenAI 相容 /v1 後端，而不是原生 OpenAI 端點：
行為是否套用
原生 OpenAI 請求塑形否
service_tier不傳送
Responses store不傳送
提示快取提示不傳送
OpenAI reasoning 相容酬載塑形不套用
隱藏的 OpenClaw 歸因標頭不會注入自訂基礎 URL
對於 Qwen 模型，當伺服器預期 Qwen 聊天範本 kwargs 時，請在模型列上設定 compat.thinkingFormat: "qwen-chat-template"。這些模型會公開二元 /think 設定檔（off、on），因為 Qwen 聊天範本思考是開/關旗標，而不是 OpenAI 樣式的 effort 階梯。
{
  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。
對於已關閉思考的 vllm/nemotron-3-* 模型，隨附外掛會傳送：
{
  "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 文件針對 Qwen2.5 模型記載 hermes，針對 Qwen3-Coder 模型記載 qwen3_xml。症狀：skills/工具從未執行、助理輸出原始 JSON/XML，例如 {"name":"read","arguments":...}，或 vLLM 在 OpenClaw 傳送 tool_choice: "auto" 時傳回空的 tool_calls 陣列。某些 Qwen/vLLM 組合只有在請求使用 tool_choice: "required" 時才會傳回結構化工具呼叫。使用 params.extra_body 逐模型強制啟用：
{
  agents: {
    defaults: {
      models: {
        "vllm/Qwen-Qwen2.5-Coder-32B-Instruct": {
          params: {
            extra_body: {
              tool_choice: "required",
            },
          },
        },
      },
    },
  },
}
請將模型 ID 替換為 openclaw models list --provider vllm 中的確切 ID，或從命令列介面套用相同覆寫：
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",
        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",
        timeoutSeconds: 300,
        models: [{ id: "your-model-id", name: "Local vLLM Model" }],
      },
    },
  },
}
timeoutSeconds 只套用於 vLLM 模型 HTTP 請求：連線建立、回應標頭、本文串流，以及總體受保護擷取中止。它也會將此提供者的 LLM 閒置/串流監看上限提高到隱含的約 120 秒預設值以上。請優先使用此設定，而不是提高 agents.defaults.timeoutSeconds，後者控制整個代理執行。
如果請求因驗證錯誤而失敗，請設定符合伺服器組態的真實 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：
  • 使用該模型正確的剖析器/範本啟動 vLLM。
  • 使用 openclaw models list --provider vllm 確認確切模型 ID。
  • 只有在 tool_choice: "auto" 仍傳回空白或純文字工具呼叫時，才新增專用逐模型 params.extra_body.tool_choice: "required" 覆寫。
更多協助：疑難排解 和 常見問題。

​
相關

模型選取

選擇提供者、模型參照和容錯移轉行為。

OpenAI

原生 OpenAI 提供者和 OpenAI 相容路由行為。

OAuth 和驗證

驗證詳細資料與憑證重用規則。

疑難排解

常見問題及其解決方式。